commission

See the User’s Guide for more discussion.

commission()

public, constructor

The default constructor initializes the data members to meaningful, possibly useful, defaults.

appointed_minister

A null pointer. This commission is useless without it, so you need to supply one later.

range

No range specified, does not restrict, tries to handle all messages. This is non-optimal and a range should be provided, but it doesn’t change the meaning.

rangefunc

A null pointer. This is an optional feature and null means it is not being used.

schedule

Set to Normal, which is the value you should use unless trying to order the handlers.

id

Set to 0, which is usual if you are not using multiple insertions of the same appointed_minister.

A default constructor is supplied so that arrays of this type can be created.

commission(const commission&)

public, constructor

The copy constructor is unsurprising.

~commission()

public, destructor

The destructor is unsurprising in that it destructs all the member data. Note however that it is not virtual. This class contains no virtual functions, so there is nothing that can be overridden. Furthermore, the message_parliament contains an array of commission objects. You can’t store a derived instance in an array element, and assigning it there would “slice” it.

commission& operator= (const commission&)

public

The copy assignment operator is unsurprising.

baro appointed_minister

public, data

This points to the minister that will fill this commission. Being a baro smart pointer, it can point to an object that no longer exists. The real point is that this does not participate in the ownership reference count of the minister (unless you explictly want it to). This prevents circular references where messages are handled by a parent window, and allows a minister destructor to revoke its commissions rather than the existance of commissions preventing the destructor from being called.

Destroying a minister should revoke any of its comissions, but there might be threading issues: message_parliament::remove does not affect an iteration in-progress, so a currently handling message may encounter the commission that refers to a minister that has already been destructed. The baro handles this case without any problem.

This will normally be set via the message_parliament::add function.

Add xref to the user's guides after they are fleshed out

typedef classics::baro<minister> baro

public, type

int id

public, data

The id is used to allow a single minister to distinguish between multiple commissions pointing to it. This is passed to minister::administer_message as part of its state parameter. If it is not needed, it is set to zero by convention.

This will normally be set via the message_parliament::add function.

message_range range

public, data

When the list of commissions is being traversed to handle a message, this value is used to skip calling minister::administer_message if the message identifier is clearly out of range for the minister to handle. More significantly, it can skip resolving the baro before attempting to make the call.

This will normally be set via the message_parliament::add function.

See also: rangefunc

bool (*rangefunc)(unsigned)

public, data

This fills the same purpose as range: to prevent the need to resolve the baro (smart pointer) to the appointed_minister if the windows message is not going to be handled by it.

While range is a quick approximation (see description of class message_range), this optional mechanism allows more exact identification. If not null, the function pointed to is called with the message identifier. If the function returns false, then this commission will not handle the message and the call to the appointed_minister is avoided.

In the future, the message_parliament may do cacheing and fancier optimization of message dispatching. So, if this function returns false, it means that this commission will never handle a message with that number, and it may remember enough to sometimes skip the commission altogether. So, the logic of the rangefunc should not be state or context dependant, but should return what this comission can, in principle, take care of.

Note that this is an ordinary pointer to a function. The normal use is to point it to a static member of the minister class. If you want to get fancier with it (perhaps by using closures), beware of object lifetime issues. The appointed_minister can deal with asynchronous object destruction, and the iteration mechanism relies on this. No such guarding is performed with the rangefunc value, since that would defeat the purpose of having it. If you point it to something that has a lifetime (normal static or non-member functions never disappear), understand the lifetime dependancy issues!

schedule_t schedule

public, data

This controls the sort-order—that is, the traversal order— of this commission in the list. It also controls (by setting the always flag) whether a commission will be used even after the message has been handled by a previous commission.

This will normally be set via the message_parliament::add function.