The Nebula Device 3: Messaging::AsyncPort Class Reference

The Nebula Device 3

Messaging::AsyncPort Class Reference

#include <asyncport.h>

Inheritance diagram for Messaging::AsyncPort:

Core::RefCounted AsyncGraphics::AsyncGraphicsInterface AsyncHttp::AsyncHttpInterface


Detailed Description

The AsyncPort class runs its handlers in a separate thread, so that message processing happens in a separate thread and doesn't block the main thread. Instead, subclasses of AsyncPort are responsible for creating the handler thread and creating and attaching the handlers to the port.

(C) 2006 Radon Labs GmbH

Public Member Functions

 AsyncPort ()
 constructor
virtual ~AsyncPort ()
 destructor
void SetName (const Util::String &n)
 set the name of the async port (required)
const Util::StringGetName () const
 get the name of the async port
void SetThreadPriority (Threading::Thread::Priority pri)
 set optional thread priority
Threading::Thread::Priority GetThreadPriority () const
 get optional thread priority
void SetThreadStackSize (unsigned int s)
 set optional thread stack size
unsigned int GetThreadStackSize () const
 get optional thread stack size
void SetWaitForMessages (bool b)
 wait-for-messages or run-continously? (default is wait-for-message)
bool GetWaitForMessages () const
 get wait-for-message mode
void AttachHandler (const Ptr< Handler > &h)
 attach a handler to the port (call before open!)
virtual void Open ()
 open the async port
virtual void Close ()
 close the async port
bool IsOpen () const
 return true if port is open
void Send (const Ptr< Message > &msg)
 send an asynchronous message to the port
void SendWait (const Ptr< Message > &msg)
 send a message and wait for completion
void Wait (const Ptr< Message > &msg)
 wait for a message to be handled
bool Peek (const Ptr< Message > &msg)
 peek a message whether it has been handled
void Cancel (const Ptr< Message > &msg)
 cancel a pending message
void Flush ()
 wait until all pending messages have been handled
int GetRefCount () const
 get the current refcount
void AddRef ()
 increment refcount by one
void Release ()
 decrement refcount and destroy object if refcount is zero
bool IsInstanceOf (const Rtti &rtti) const
 return true if this object is instance of given class
bool IsInstanceOf (const Util::String &className) const
 return true if this object is instance of given class by string
bool IsInstanceOf (const Util::FourCC &classFourCC) const
 return true if this object is instance of given class by fourcc
bool IsA (const Rtti &rtti) const
 return true if this object is instance of given class, or a derived class
bool IsA (const Util::String &rttiName) const
 return true if this object is instance of given class, or a derived class, by string
bool IsA (const Util::FourCC &rttiFourCC) const
 return true if this object is instance of given class, or a derived class, by fourcc
const Util::StringGetClassName () const
 get the class name
Util::FourCC GetClassFourCC () const
 get the class FourCC code

Static Public Member Functions

static void DumpRefCountingLeaks ()
 dump refcounting leaks, call at end of application (NEBULA3_DEBUG builds only!)

Protected Member Functions

virtual void OnCreateHandlers ()
 derive in subclass, create and attach handlers from here

Member Function Documentation

void Messaging::AsyncPort::AttachHandler ( const Ptr< Handler > &  h  ) 

attach a handler to the port (call before open!)

Called by OnCreateHandlers() method of subclass to attach a handler to the port.

void Messaging::AsyncPort::Open (  )  [virtual]

open the async port

Open the async port. The async port needs a valid name before it is opened. Messages can only be sent to an open port. This method will first call OnCreateHandlers() and then create the handler thread.

Reimplemented in AsyncHttp::AsyncHttpInterface, and AsyncGraphics::AsyncGraphicsInterface.

void Messaging::AsyncPort::Close (  )  [virtual]

close the async port

Closes the async port.

void Messaging::AsyncPort::Send ( const Ptr< Message > &  msg  ) 

send an asynchronous message to the port

Handle an asynchronous message and return immediately. If the caller expects any results from the message he can poll with the AsyncPort::Peek() method, or he may wait for the message to be handled with the AsyncPort::Wait() method.

void Messaging::AsyncPort::SendWait ( const Ptr< Message > &  msg  ) 

send a message and wait for completion

Send an asynchronous message and wait until the message has been handled.

void Messaging::AsyncPort::Wait ( const Ptr< Message > &  msg  ) 

wait for a message to be handled

This method will wait until a message has been handled. If the caller expects any return arguments from the message handling it can use this method to wait for the results.

bool Messaging::AsyncPort::Peek ( const Ptr< Message > &  msg  ) 

peek a message whether it has been handled

This method peeks whether a message has already been handled. If the caller expects any return arguments from the message handling it can use this message to check whether the results are ready using this non-blocking method. The caller can also wait for the results to become ready using the Wait() method.

void Messaging::AsyncPort::Cancel ( const Ptr< Message > &  msg  ) 

cancel a pending message

This method will cancel a pending message.

void Messaging::AsyncPort::Flush (  ) 

wait until all pending messages have been handled

This method will wait until ALL pending messages have been handled. Note that this method will be called automatically before the AsyncPort shutsdown.

void Messaging::AsyncPort::OnCreateHandlers (  )  [protected, virtual]

derive in subclass, create and attach handlers from here

This message is called by Open() when message handlers should be created and attached via AttachHandler(). Override this method in a subclass.

Reimplemented in AsyncHttp::AsyncHttpInterface, and AsyncGraphics::AsyncGraphicsInterface.

int Core::RefCounted::GetRefCount (  )  const [inline, inherited]

get the current refcount

Return the current refcount of the object.

void Core::RefCounted::AddRef (  )  [inline, inherited]

increment refcount by one

Increment the refcount of the object.

void Core::RefCounted::Release (  )  [inline, inherited]

decrement refcount and destroy object if refcount is zero

Decrement the refcount and destroy object if refcount is zero.

const Util::String & Core::RefCounted::GetClassName (  )  const [inline, inherited]

get the class name

Get the class name of the object.

Util::FourCC Core::RefCounted::GetClassFourCC (  )  const [inline, inherited]

get the class FourCC code

Get the class FourCC of the object.

void Core::RefCounted::DumpRefCountingLeaks (  )  [static, inherited]

dump refcounting leaks, call at end of application (NEBULA3_DEBUG builds only!)

This method should be called as the very last before an application exits.