SHandler Class Reference
[Utility Classes and Functions]

#include <support/Handler.h>

Inheritance diagram for SHandler:

Detailed Description

SHandler is an event queue to deliver and process SMessage objects.

The SHandler is a base class for executing asynchronous operations and/or performing serialization of those operations. It is a mechanism for implementing concurrency.

SHandler provides a set of posting methods for placing SMessage data into an execution queue. Each message in the queue is timestamped, and the messages in the queue are consecutively processed by SHandler in their timestamped order.

Message delivery is asynchronous: your thread can return from delivering a message before the message has even started execution. However, to ensure the correct delivery order of the messages, the handler only processes one at a time.

Messages are sent to a SHandler by calling one of PostMessage(), PostMessageAtTime(), PostDelayedMessage(), or EnqueueMessage(). You subclass from SHandler and override HandleMessage() to process messages that have been posted to the handler.

SHandler can also be used to serialize with external operations. To do this, pass in an external lock to the constructor. This lock will then be acquired when calling HandleMessage. In this way, the serialization of SHandler message handling can be also synchronized with external operations.

See SHandler Patterns for many examples of threading techniques you can use with SHandler.

Posting

APIs to place messages into the handler's message queue.

enum { POST_REMOVE_DUPLICATES = 0x0001, POST_KEEP_UNIQUE = 0x0002 }

Flags for PostMessage(), PostDelayedMessage(), PostMessageAtTime(), EnqueueMessage(). More...

status_t EnqueueMessage (const SMessage &message, nsecs_t time, uint32_t flags=0)

Deposit a message a message into the handler's queue.

status_t PostDelayedMessage (const SMessage &message, nsecs_t delay, uint32_t flags=0)

Post a message to the handler, with a timestamp set to the current time plus delay.

status_t PostMessage (const SMessage &message, uint32_t flags=0)

Post a message to the handler, with its timestamp set to the current time.

status_t PostMessageAtTime (const SMessage &message, nsecs_t absoluteTime, uint32_t flags=0)

Post a message to the handler, which is expected to arrive at the time absoluteTime.

Queue Manipulation

APIs to manipulate message in the queue queue.

enum { FILTER_REVERSE_FLAG = 0x0001, FILTER_FUTURE_FLAG = 0x0002 }

Flags for FilterMessages() and RemoveMessages(). More...

enum filter_action { FILTER_REMOVE = 0, FILTER_KEEP = 1, FILTER_STOP = 2 }

Actions you can return to FilterMessages() from your filter_func. More...

typedef filter_action(* filter_func )(const SMessage *message, void *data)

Function callback for FilterMessages().

int32_t CountMessages (uint32_t what=B_ANY_WHAT)

Return the number of pending message that match what.

void FilterMessages (const filter_functor_base &functor, uint32_t flags, void *data, SMessageList *outRemoved=NULL)

Flags for FilterMessages() and RemoveMessages().

void FilterMessages (filter_func func, uint32_t flags, void *data, SMessageList *outRemoved=NULL)

Iterate through this handler's message queueue, selecting whether to keep or remove messages.

void RemoveAllMessages (SMessageList *outRemoved=NULL)

Perform FilterMessages() where all messages are deleted.

void RemoveMessages (uint32_t what, uint32_t flags, SMessageList *outRemoved=NULL)

Perform FilterMessages() where all messages that match what are deleted.

Dispatching Primitives

Low-level manipulation of the handler's message dispatching.
Note:
These should not be used unless you absolutely know what you are doing.

SMessage * DequeueMessage (uint32_t what)

Remove next pending message with code what from the handler's message queue.

void DispatchAllMessages ()

Immediately handle all messages currently in the queue.

nsecs_t NextMessageTime (int32_t *out_priority)

Return the time of the next message in the queue.

Handling

APIs used to handle messages that are delivered to the handler.

virtual status_t HandleMessage (const SMessage &msg)

Subclasses override this to receive messages.

void ResumeScheduling ()

Make handler ready to process the next message in its queue.

Bookkeeping

Creation, destruction, locking, etc.

SHandler (const SContext &context)

SHandler (SLocker *externalLock)

Supply an external lock to be held when dispatching messages.

SHandler ()

virtual ~SHandler ()

Friends

class BProcess

Classes

class filter_functor

class filter_functor_base

Functor callback for FilterMessages(). More...

Member Typedef Documentation

typedef filter_action(* filter_func)(const SMessage *message, void *data)

Function callback for FilterMessages().

See also:
FilterMessages()

Member Enumeration Documentation

anonymous enum

Flags for PostMessage(), PostDelayedMessage(), PostMessageAtTime(), EnqueueMessage().

Enumerator:

POST_REMOVE_DUPLICATES Remove any pending message with the same What() code.
Using this flag is a semantically the same as first calling RemoveMessages(msgCode) before posting the message, but more efficient. This is as opposed to POST_KEEP_UNIQUE.
Note:
be careful with POST_REMOVE_DUPLICATES, as the data for any existing messages in the queue will be released inside of the call. That means, if you aren't absolutely sure about what that data is, you MUST NOT do this while holding a lock.

POST_KEEP_UNIQUE Ensure this message's event code is unique in the queue.
This flag ensures that only one message with the given message code exists in the queue. If, at the time of posting, there are already messages with the same code, the first such message will be kept with its data changed (moving it up earlier in the queue if needed for the new timestamp), and all other messages removed. Unlike POST_REMOVE_DUPLICATES, posting a new message when there is already a pending message with the same code will not cause that message code to be moved later in the queue.
Note:
be careful with POST_KEEP_UNIQUE, as the data for any existing messages in the queue will be released inside of the call. That means, if you aren't absolutely sure about what that data is, you MUST NOT do this while holding a lock.

Reimplemented from SAtom.

anonymous enum

Flags for FilterMessages() and RemoveMessages().

Enumerator:

FILTER_REVERSE_FLAG Filter in reverse time order.

FILTER_FUTURE_FLAG Include messages after current time.

enum filter_action

Actions you can return to FilterMessages() from your filter_func.

Enumerator:

FILTER_REMOVE Remove message from queue.

FILTER_KEEP Keep message in queue.

FILTER_STOP Do not filter any more messages.

Constructor & Destructor Documentation

SHandler ( )

Deprecated:
SHandler is no longer a BBinder object.

SHandler ( SLocker * externalLock )

Supply an external lock to be held when dispatching messages.

SHandler ( const SContext & context )

Deprecated:
SHandler is no longer a BBinder object.

~SHandler ( ) [protected, virtual]

Deprecated:
SHandler is no longer a BBinder object.

Member Function Documentation

int32_t CountMessages ( uint32_t what = B_ANY_WHAT )

Return the number of pending message that match what.

SMessage * DequeueMessage ( uint32_t what )

Remove next pending message with code what from the handler's message queue.
You are responsible for deleting the returned message. If there are no matching pending message, NULL is returned.

void DispatchAllMessages ( )

Immediately handle all messages currently in the queue.

status_t EnqueueMessage ( const SMessage & message,

nsecs_t time,

uint32_t flags = 0

)

Deposit a message a message into the handler's queue.
The message will be delivered at the given absolute time.
Note:
Unlike PostMessageAtTime(), this function does not try to prevent starvation by ensuring the time is later than now.

void FilterMessages ( const filter_functor_base & functor,

uint32_t flags,

void * data,

SMessageList * outRemoved = NULL

)

Flags for FilterMessages() and RemoveMessages().

void FilterMessages ( filter_func func,

uint32_t flags,

void * data,

SMessageList * outRemoved = NULL

)

Iterate through this handler's message queueue, selecting whether to keep or remove messages.
Your filter_func selects the action to perform for each message by the result it turns. If it selects to remove a message, the message will either be placed into outRemoved if that is non-NULL, or immediately deleted.
Note:
filter_func is called WITH THE HANDLER LOCKED. You can not call back into the handler from it, and must be very careful about what other locks you acquire.

status_t HandleMessage ( const SMessage & msg ) [virtual]

Subclasses override this to receive messages.

Reimplemented in BInformant, BSerialObserver, and BTokenSource.

nsecs_t NextMessageTime ( int32_t * out_priority )

Return the time of the next message in the queue.

status_t PostDelayedMessage ( const SMessage & message,

nsecs_t delay,

uint32_t flags = 0

)

Post a message to the handler, with a timestamp set to the current time plus delay.

See also:
PostMessageAtTime()

status_t PostMessage ( const SMessage & message,

uint32_t flags = 0

)

Post a message to the handler, with its timestamp set to the current time.

See also:
PostMessageAtTime()

status_t PostMessageAtTime ( const SMessage & message,

nsecs_t absoluteTime,

uint32_t flags = 0

)

Post a message to the handler, which is expected to arrive at the time absoluteTime.
The handler will enqueue this message, but not deliver it until after the selected time. If the timestamp is set to the current time, the message will be delivered as soon as possible, but not before any older pending messages have been handled. Normally, a handler executes only one message at a time, in their timestamp order.
This method ensures that absoluteTime is later than the current time, to protect against livelocks. You can use EnqueueMessage() to avoid this constraint.
The optional flags may be POST_REMOVE_DUPLICATES or POST_KEEP_UNIQUE.

See also:
PostMessage(), PostDelayedMessage(), EnqueueMessage()

void RemoveAllMessages ( SMessageList * outRemoved = NULL )

Perform FilterMessages() where all messages are deleted.

See also:
FilterMessages()

void RemoveMessages ( uint32_t what,

uint32_t flags,

SMessageList * outRemoved = NULL

)

Perform FilterMessages() where all messages that match what are deleted.

See also:
FilterMessages()

void ResumeScheduling ( )

Make handler ready to process the next message in its queue.
You can call this function while in your HandleMessage() method to let the handler schedule itself for the next message in its queue, allowing it to continue processing even before you have returned from HandleMessage().

Friends And Related Function Documentation

friend class BProcess [friend]

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


Posting
APIs to place messages into the handler's message queue.
enum	{ POST_REMOVE_DUPLICATES = 0x0001, POST_KEEP_UNIQUE = 0x0002 }
	Flags for PostMessage(), PostDelayedMessage(), PostMessageAtTime(), EnqueueMessage(). More...
status_t	EnqueueMessage (const SMessage &message, nsecs_t time, uint32_t flags=0)
	Deposit a message a message into the handler's queue.
status_t	PostDelayedMessage (const SMessage &message, nsecs_t delay, uint32_t flags=0)
	Post a message to the handler, with a timestamp set to the current time plus delay.
status_t	PostMessage (const SMessage &message, uint32_t flags=0)
	Post a message to the handler, with its timestamp set to the current time.
status_t	PostMessageAtTime (const SMessage &message, nsecs_t absoluteTime, uint32_t flags=0)
	Post a message to the handler, which is expected to arrive at the time absoluteTime.
Queue Manipulation
APIs to manipulate message in the queue queue.
enum	{ FILTER_REVERSE_FLAG = 0x0001, FILTER_FUTURE_FLAG = 0x0002 }
	Flags for FilterMessages() and RemoveMessages(). More...
enum	filter_action { FILTER_REMOVE = 0, FILTER_KEEP = 1, FILTER_STOP = 2 }
	Actions you can return to FilterMessages() from your filter_func. More...
typedef filter_action(*	filter_func )(const SMessage message, void data)
	Function callback for FilterMessages().
int32_t	CountMessages (uint32_t what=B_ANY_WHAT)
	Return the number of pending message that match what.
void	FilterMessages (const filter_functor_base &functor, uint32_t flags, void data, SMessageList outRemoved=NULL)
	Flags for FilterMessages() and RemoveMessages().
void	FilterMessages (filter_func func, uint32_t flags, void data, SMessageList outRemoved=NULL)
	Iterate through this handler's message queueue, selecting whether to keep or remove messages.
void	RemoveAllMessages (SMessageList *outRemoved=NULL)
	Perform FilterMessages() where all messages are deleted.
void	RemoveMessages (uint32_t what, uint32_t flags, SMessageList *outRemoved=NULL)
	Perform FilterMessages() where all messages that match what are deleted.
Dispatching Primitives
Low-level manipulation of the handler's message dispatching. Note: These should not be used unless you absolutely know what you are doing.
SMessage *	DequeueMessage (uint32_t what)
	Remove next pending message with code what from the handler's message queue.
void	DispatchAllMessages ()
	Immediately handle all messages currently in the queue.
nsecs_t	NextMessageTime (int32_t *out_priority)
	Return the time of the next message in the queue.
Handling
APIs used to handle messages that are delivered to the handler.
virtual status_t	HandleMessage (const SMessage &msg)
	Subclasses override this to receive messages.
void	ResumeScheduling ()
	Make handler ready to process the next message in its queue.
Bookkeeping
Creation, destruction, locking, etc.
	SHandler (const SContext &context)
	SHandler (SLocker *externalLock)
	Supply an external lock to be held when dispatching messages.
	SHandler ()
virtual	~SHandler ()
Friends
class	BProcess
Classes
class	filter_functor
class	filter_functor_base
	Functor callback for FilterMessages(). More...

SHandler Class Reference [Utility Classes and Functions]

Detailed Description

Posting

Queue Manipulation

Dispatching Primitives

Handling

Bookkeeping