VCF::Delegate

VCF::Delegate Class Reference

A delegate can be thought of as a function pointer on steroids. More...

#include <vcf/FoundationKit/Delegates.h>

Inheritance diagram for VCF::Delegate:


Public Member Functions
	Delegate ()
virtual	~Delegate ()
Delegate &	operator= (const Delegate &rhs)
bool	empty () const
	Returns whether or not the delegate has any callbacks.
size_t	size () const
	Returns the number of callbacks currently associated with this delegate.
void	clear ()
	cleans out all callbacks from the delegate.
void	add (CallBack *callback)
	Adds a callback to a delegate.
void	remove (CallBack *callback)
	Removes a callback from a delegate.
Delegate &	operator-= (CallBack *callback)
const CallBack &	at (const uint32 &index) const
	Returns the callback at the specific index.
void	setRunCallbacksAsynchronously (bool val)
	Tells the delegate whether the callbacks should be invoked in a synchronous manner or asynchronously.
bool	getCallbacks (CallBack::Vector &val)
	This allows you to retreive a copy of the callbacks registered with this delegate.
Static Public Member Functions
static void	initThreadPool ()
	Initializes the thread pool used by delegates for asynchronous callback invocation.
static void	terminateThreadPool ()
	Terminates the thread pool used by delegates for asynchronous callback invocation.
static ThreadPool *	getThreadPool ()
	Get's the current trhead pool used by delegates for asynchronous callback invocation.
Protected Member Functions
void	checkHandlers ()
Protected Attributes
CallBack::Vector *	functions
bool	runCallbacksAsync_
Static Protected Attributes
static ThreadPool *	delegateThreadPool

Detailed Description

A delegate can be thought of as a function pointer on steroids.

A delegate stores a collection of callbacks, or function pointers, and when you "invoke" the delegate, the delegate passes the function arguments to each of it's callbacks. It is essentially the same idea as .Net's multicast delegate. Therefore all delegates in the VCF can have multiple "outputs" or callbacks.

Like a function a delegate has a function signature and takes 0 or more arguments and may or may not return a value. The delegate derives from FunctionTypeInfo so that it can store information about it's function signature. This is used to make sure that any added callbacks actually match the function signature of the delegate. For instance, if you had a delegate with a function signature of

void (delegate)(int, double)

and tried to add a callback with a function signature of

void (callback)(double,int)

the result would be the throwing of an exception since the signature's do not match.

A delegate may have 0 or more callbacks associated with it, and when the delegate is destroyed it removes all it's callbacks. When a callback is removed from the delegate, the delegate makes sure the callback removes the delegate from the callbacks's internal list as well. In other words, both the callback and the delegate keep references to each other, and both need to be cleaned up when a callback is removed from a delegate.

A delegate is invoked by calling the invoke method and passing in the appropriate arguments. This in turn will iteratate through all the callbacks registered with the delegate and invoke each callback's bound function pointer. The invoke usage looks something like this:

//define function..
bool duhDoIt( const String& str, double d );

//define a delegate with a bool return value and two 
//function arguments:
Delegate2R<bool,const String&,double> myDelegate;

//add the static function pointer to delegate
myDelegate += duhDoIt; 

//invoke the delegate
myDelegate.invoke("Hola", 120.456);

This will call the duhDoIt() function and pass in "Hola" and 120.456 as arguments to the function. You can use the operator() shorthand if you prefer:

//invoke the delegate
myDelegate("Hola", 120.456);

it will call invoke() for you.

Note that once invoke() is called, it will block until all the callbacks have been called and completed. If you have a lengthy operation in a callback then this may take a while. This leads us to wanting some sort of asynchronous invocation mode.

You can invoke a delegate asynchronously by using the beginInvoke() method as well as the AsyncResult class. You start the async invocation out by calling beingInvoke(), passing in the delegate's function arguments, and an optional callback that is triggered once all the callbacks have completed. The beginInvoke() call will return immediately and give you a new AsyncResult instance which is now your responsibility to delete.

With the AsyncResult instance you can call it's wait() method to block until all of the callbacks have finished executing. For example

void myFunc( int i );

Delegate1<int> d2;
d2 += doit;

AsyncResult* ar = d2.beginInvoke( 10, NULL );
ar->wait();//block till we're done
delete ar;

There is static ThreadPool for Delegates to use when they are operating in asynchronous mode. The lifetime of the thread pool is managed by the framework and created and deleted automatically.

Like the CallBack class, delegates may be broken down into two categories, those that do not return any value and those that do. For delegates that do not return anything the derived classes are named DelegateX where X is the number of arguments that the delegate function takes. For delegates that do return a value the classes are named DelegateRX where where X is the number of arguments that the delegate function takes and the R indicates that the delegate has a return type.

See also:: DelegateR

Constructor & Destructor Documentation

VCF::Delegate::Delegate ( ) [inline]

virtual VCF::Delegate::~Delegate ( ) [inline, virtual]

Member Function Documentation

void VCF::Delegate::add ( CallBack * callback ) [inline]

Adds a callback to a delegate.
If the callback function signature does not match the delegate function signature then the callback is not added and the function throws a RuntimeException.

const CallBack& VCF::Delegate::at ( const uint32 & index ) const [inline]

Returns the callback at the specific index.
If the delegate has no callbacks, or if the index is out of bounds then an exception is thrown.

void VCF::Delegate::checkHandlers ( ) [inline, protected]

void VCF::Delegate::clear ( ) [inline]

cleans out all callbacks from the delegate.
Note that this does not delete the callback.

bool VCF::Delegate::empty ( ) const [inline]

Returns whether or not the delegate has any callbacks.

bool VCF::Delegate::getCallbacks ( CallBack::Vector & val ) [inline]

This allows you to retreive a copy of the callbacks registered with this delegate.

Parameters:

CallBack::Vector a reference to a std::vector<CallBack*> that will be filled with the callbacks registered with this delegate.

Returns:
bool returns true if the callbacks were successfully copied over. Otherwise returns false. A delegate with no callbacks will also return false.

static ThreadPool* VCF::Delegate::getThreadPool ( ) [static]

Get's the current trhead pool used by delegates for asynchronous callback invocation.

static void VCF::Delegate::initThreadPool ( ) [static]

Initializes the thread pool used by delegates for asynchronous callback invocation.
This is called by the framework.

Delegate& VCF::Delegate::operator-= ( CallBack * callback ) [inline]

See also:
remove

Delegate& VCF::Delegate::operator= ( const Delegate & rhs ) [inline]

void VCF::Delegate::remove ( CallBack * callback ) [inline]

Removes a callback from a delegate.
This does not delete the callback.

void VCF::Delegate::setRunCallbacksAsynchronously ( bool val ) [inline]

Tells the delegate whether the callbacks should be invoked in a synchronous manner or asynchronously.
This is only relevant when you invoke a delagate in async mode. When this happens, and the thread pool determines that it's time to invoke the delegate's various callbacks it has a choice: 1) to invoke each callback, blocking until the callback returns or 2) to post each callback to the delegate thread pool for asynchronous execution. If the delegate is set to run callbacks asynchronously then option 2 is used, otherwise option 1 is performed. The default is option 1.

size_t VCF::Delegate::size ( ) const [inline]

Returns the number of callbacks currently associated with this delegate.

static void VCF::Delegate::terminateThreadPool ( ) [static]

Terminates the thread pool used by delegates for asynchronous callback invocation.
This is called by the framework.

Member Data Documentation

ThreadPool* VCF::Delegate::delegateThreadPool [static, protected]

CallBack::Vector* VCF::Delegate::functions [protected]

bool VCF::Delegate::runCallbacksAsync_ [protected]

The documentation for this class was generated from the following file:

vcf/FoundationKit/Delegates.h

VCF::Delegate Class Reference

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation