Sourceforge.net - The VCF's Project Host
   The VCF Website Home   |   Online Discussion Forums   |   Sourceforge.net Project Page   

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:

VCF::FunctionTypeInfo VCF::Delegate0 VCF::Delegate1< P1 > VCF::Delegate1R< ReturnType, P1 > VCF::Delegate2< P1, P2 > VCF::Delegate2R< ReturnType, P1, P2 > VCF::Delegate3< P1, P2, P3 > VCF::Delegate3R< ReturnType, P1, P2, P3 > VCF::Delegate4< P1, P2, P3, P4 > VCF::Delegate4R< ReturnType, P1, P2, P3, P4 > VCF::Delegate5< P1, P2, P3, P4, P5 > VCF::Delegate5R< ReturnType, P1, P2, P3, P4, P5 > VCF::Delegate6< P1, P2, P3, P4, P5, P6 > VCF::Delegate6R< ReturnType, P1, P2, P3, P4, P5, P6 > VCF::Delegate7< P1, P2, P3, P4, P5, P6, P7 > VCF::Delegate8< P1, P2, P3, P4, P5, P6, P7, P8 > VCF::DelegateR< ReturnType > List of all members.

Public Member Functions

 Delegate ()
virtual ~Delegate ()
Delegateoperator= (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.
Delegateoperator-= (CallBack *callback)
const CallBackat (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 ThreadPoolgetThreadPool ()
 Get's the current trhead pool used by delegates for asynchronous callback invocation.

Protected Member Functions

void checkHandlers ()

Protected Attributes

CallBack::Vectorfunctions
bool runCallbacksAsync_

Static Protected Attributes

static ThreadPooldelegateThreadPool

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:
   Comments or Suggestions?    License Information