control-policy.hpp File Reference

Go to the source code of this file.

Description

Definition of special cases when imposing a change onto concrete time values.

The time::Control element allows to impose modifications to a connected time value entity and at the same time publish the changes to registered listeners. Due to the various flavours of actual time value entities, this is a complex undertaking, which is implemented here based on policies and template metaprogramming.

The header control-impl.hpp defines the building blocks for time::Control and then includes this header here to get the concrete template specialisations for time::mutation::Policy. This policy class is templated by time entity types

• for TI, the nominal value type used on the time::Control interface
• for SRC, the actual type of values to impose as change
• for TAR, the target time value's type, receiving those changes.

mutating a time value entity

Actually imposing a change to the attached time value entity involves several steps. Each of these steps might be adapted specifically, in accordance to the concrete time value types involved.

• TimeValue, Time
• Offset
• Duration
• TimeSpan
• QuTime (grid aligned time value)
• QuTimeSpan (planned as of 6/2011)

Moreover, the combination of types needs to be taken into account. For example, it doesn't make sense to apply a Duration value as change to a TimeValue, which has no duration (temporal extension). While a TimeSpan might receive a Duration change, but behaves differently when imposing a Time to manipulate the starting point of the time interval given by the TimeSpan.

Incoming changes might be of any of the aforementioned types, and in addition, we might receive nudging, which means to increment or decrement the target time value in discrete steps. After maybe adapting these incoming change values, they may be actually imposed on the target. In all cases, this is delegated to the time::Mutation base class, which is declared fried to TimeValue and thus has the exceptional ability to manipulate time values, which otherwise are defined to be immutable. Additionally, these protected functions in the time::Mutation baseclass also know how to handle nudge values, either by using the native (embedded) time grid of a quantised time value, or by falling back to a standard nudging grid, defined in the session context (TODO as of 6/2011). //////////////////////TICKET #810

After (maybe) imposing a change to the target, the change notification value needs to be built. This is the time value entity to be forwarded to registered listeners. This notification value has to be given as the type TI, in accordance to the time::Control<TI> frontend definition used in the concrete usage situation. As this type TI might be different to the actual target type, and again different to the type of the change handed in, in some cases this involves a second conversion step, to represent the current state of the target TAR in terms of the interface type TI.

changing quantised (grid aligned) time entities

The time::Control element includes the capability to handle grid aligned time values, both as target and as change/notification value. This ability is compiled in conditionally, as including mutation.hpp causes several additional includes, which isn't desirable when it comes just to changing plain time values. Thus, to get these additional specialisations, the LIB_TIME_TIMEQUANT_H header guard needs to be defined, which happens automatically if lib/time/mutation.hpp is included prior to lib/time/control.hpp.

As a special convention, any quantised (grid aligned) types involved in these time changes will be materialised, whenever a type conversion happens. Generally speaking, a quantised time value contains an (opaque) raw time value, plus a reference to a time grid definition to apply. In this context materialising means actually to apply this time grid to yield a grid aligned value. Thus, when using a quantised value to impose as change (or to receive a change), its grid aligning nature becomes effective, by applying the current definition of the grid to create a fixed (materialised) time value, aligned to that current grid.

Todo:

6/2011 include all the special cases for QuTimeSpan ////////////////////TICKET #760

See also

TimeControl_test

Definition in file control-policy.hpp.

#include "lib/time/mutation.hpp"
#include "lib/time/timevalue.hpp"
#include <boost/utility/enable_if.hpp>
#include <type_traits>
#include <functional>

Classes
struct	Builder< TI, TAR >
	Implementation policy: how to build a new notification value of type TI, given a target time value entity of type TAR. More...
struct	Builder< TimeSpan, Duration >
struct	Builder< TimeSpan, TAR >
struct	Builder< TimeSpan, TimeSpan >
struct	canMutateDuration< T >
struct	canReceiveDuration< T >
struct	Link< TI, TAR >
	Policy to tie the various detail policies together for providing actual value change operations. More...
struct	Policy< TI, SRC, TAR >
	Policy how to impose changes onto a connected target time value entity This policy will be parametrised with the concrete time entity types involved in the usage situation of time::Control. More...
struct	Policy< Duration, typename disable_if< canReceiveDuration< TAR >, Duration >::type, TAR >
	special case: a Duration change value can't be imposed to a plain time value. More...
struct	Policy< TI, Duration, TimeSpan >
struct	Policy< TI, SRC, typename disable_if< canMutateDuration< SRC >, Duration >::type >
	special case: a Duration target value can't be changed by plain time values. More...
struct	Policy< TI, TimeSpan, Duration >
struct	Policy< TimeSpan, TimeSpan, TimeSpan >

Functions
template<class T >
bool	isDuration ()
template<class T >
bool	isTimeSpan ()
template<class T >
T const &	maybeMaterialise (T const &non_grid_aligned_TimeValue)

Namespaces
	lib
	Implementation namespace for support and library code.