[section Policies Framework]

[heading Introduction]
Policy-based class design is a well-known and oft-used in generic library design
that promotes the definition of classes that are parameterized over various aspects
of their implementation. In general, a /policy/ encapsulates an implementation
detail of a data structure that is orthoganal to the its primary concerns. Probably
the most well-known example of policies is the Standard Library's `std::Allocator`
concept. Every container in the Standard Library supports a template parameter
that can be used to alter the allocation mechanism of the underlying container.

Unfortunately, policy-based class design has one drawback: too many template
parameters. This is especially true of data structures that support many different
policies, each requiring a new template paramter. One way of avoiding a multiplicity
of template parameters is to encapsulate a sequence policies in a type sequence.
This is the approach taken by the Boost.Math library to implement its various
rounding, type promoting, and error handling policies.

The Origin C++0x libraries provide a generalized implementation of the approach
used in the Boost.Math library that uses variadic templates to implement type
sequences.

[note What makes a good policy?]

[note What makes this best practice?]

[heading Policy Concepts]
There are two (or more?) kinds of policies:

*Strategy* - A strategy is a kind of policy that abstracts and implements some
feature of an implementation. The `std::Allocator` concept is an example of a
strategy. Because strategies abstract and encapsulate a component of a data structure,
they are typically defined by a concept.

*Configuration* - A configuration parameter is either an integral constant expression
or a tag class that is used to denote a specific configuration parameter of the
data structure. For example, the GCC `hashtable` implementation defines a number
of configuration parameters as boolean constants such as the caching of hash codes,
whether or not keys are unique, etc.

The realization of these kinds of policies in different libraries comes in two
distinct forms: positional and named.

A /positional policy/ is simply a fancy name for a template parameter. This is by
far the easiest way to implement a policy-based class, but also the least flexible.
Consider the definition of the `std::vector`.

 template <typename T, typename Alloc = std::allocator<T>>
 class vector { ... };

Here, the allocation policy is the second template parameter. It's position in the
template parameter list determines the interpretation of its arguments.

In contrast, a /named policy/ is a template class whose name indicates the semantics
of the policy and whose parameter(s) represent the choice of a value. From the
Boost.Math library, you can define a specific error-handling policy as a sequence
of template instances.

 typedef policies<
     domain_error<throw_on_error>,
     overvlow_error<ignore_error>
     underflow_error<ignore_error>
 > my_policies;

The benefit of this approach is that the interpretation of the semantics are embedded
in the type name, and can be separated from the position in which they occur within
the argument list. Some careful metaprogramming allows the data structure implementor
to identify and abstract these policies from the `policies` wrapper.

The Origin C++0x Libraries support both positional and named policies for data
structures.

There are two approaches to building policy sequences: aliasing and deriving. An
/aliased policy/ uses a typedef to provide an abstract name for a sequence of
policies. When used as a template argument, the policy sequence is still a part
of the type name of the parameterized data structure. This means that any compiler
messages will emit the full sequence of policies with the type. For example:

 typedef policies<domain_error<throw_on_error>> my_polices;
 cout << typestr<my_policies>(); // Prints 'policies<domain_error<throw_on_error>>'

A /derived policy/ is one that creates a new type name for a sequence of policies
by deriving from that sequence. This has the effect of eliding the entire sequence
of policy classes in the list. Because this creates a new type name, compiler
messages only list the most-derived type. For example:

 typedef policies<domain_error<throw_on_error>> my_polices;
 cout << typestr<my_policies>(); // Prints 'my_policies'

The downside to using derived policies is that they change the class structure of
the policies, and require substantially more work to integrate into the policy
framework. However, the benefit of using them is obvious if you know the specific
set of policies required for your application.

[heading Using Policies]
Write about the different policies implemented in the Origin.Core.

[heading Creating Policies]
Defining policies requires a little extra work from the programmer. In order
for a policy implementation to work with the Origin.Policy framework, the policy
author must define a policy class that models this concept. A policy class is
a template class that defines a name for the policy's.

 concept Policy<typename P> {
     typename policy_kind;
     typename type;
 };

The `Policy` concept defines the requirements of a policy class by defining a binding
between the policy name and policy value. The `policy_kind` type name denotes a tag
class that represents the actual name of the policy. The `type` type name denotes
the value of the policy.

Consider the implementation of the allocation policy:

 struct allocation_policy { };

 template <typename Alloc>
 struct allocation {
     typedef allocation_policy policy_kind;
     typedef Alloc type;
 };

Here, the `allocation_policy` tag class represents the name of the allocation
policy class. The `allocation` template class binds the name `allocation_policy`
to the value supplied by the user.

[heading Programming with Policies]
Write about actually accessing the policy values.

 policy_element<Kind, Polices>::value
 policy_element<Kind, Policies>::type

[endsect]