SMessageList Class Reference
[Utility Classes and Functions]

#include <support/MessageList.h>

Detailed Description

List of SMessage objects, used to implement message queues.

Public Member Functions

Adding

These are low-level APIs for placing messages into the list.

void AddHead (SMessage *message)

Place the given message at the front of the list.

void AddTail (SMessage *message)

Place the given message at the end of the list.

void InsertAfter (SMessage *message, const SMessage *position)

Place the given message immediately after position in the list.

void InsertBefore (SMessage *message, const SMessage *position)

Place the given message immediately before position in the list.

Creation and Destruction

SMessageList & Adopt (SMessageList &other)

Transfer ownership of messages from argument to this message list.

SMessageList ()

Transfer ownership of messages from argument to this message list.

~SMessageList ()

Transfer ownership of messages from argument to this message list.

Global Operations

Functionality that manipulates the message list as a whole.

int32_t CountMessages (uint32_t what=B_ANY_WHAT) const

Return the total number of messages in the list.

bool IsEmpty () const

Return true if there are no messages in the list.

void MakeEmpty ()

Remove all messages from the list, deleting the objects.

Queue Operations

These manage the message list as a queue, keeping the messages sorted by their timestamp order.

SMessage * DequeueMessage (uint32_t what=B_ANY_WHAT, bool *more=NULL)

Remove the next message from the queue.

void EnqueueMessage (SMessage *msg)

Place a new message into the queue.

SMessage * EnqueueMessageRemoveDups (const SMessage &msg, nsecs_t time, SValue *outPrevData, SMessageList *outRemoved)

Like EnqueueMessage(), but first removes all other messages with the same code.

SMessage * EnqueueUniqueMessage (const SMessage &msg, nsecs_t time, SValue *outPrevData, SMessageList *outRemoved)

Like EnqueueMessage(), but ensures the message code is unique in the list.

nsecs_t OldestMessage (int32_t *out_priority) const

Find information about the next message in the list.

Iteration

These APIs allow you to step over the linked list of messages.

const SMessage * Head () const

Retrieve first message in the list.

const SMessage * Next (const SMessage *current) const

Return the next message after current in the list.

const SMessage * Previous (const SMessage *current) const

Return the previous message before current in the list.

const SMessage * Tail () const

Retrieve last message in the list.

Removing

Low-level APIs for removing messages from the list.

SMessage * Remove (const SMessage *message)

Remove the given message from the list and return it.

SMessage * RemoveHead ()

Remove the first message from the list and return it.

SMessage * RemoveTail ()

Remove the last message from the list and return it.

Constructor & Destructor Documentation

SMessageList ( )

Transfer ownership of messages from argument to this message list.
Messages are merged to this in timestamp order. The other list is empty upon return.

~SMessageList ( )

Transfer ownership of messages from argument to this message list.
Messages are merged to this in timestamp order. The other list is empty upon return.

Member Function Documentation

void AddHead ( SMessage * message )

Place the given message at the front of the list.

void AddTail ( SMessage * message )

Place the given message at the end of the list.

SMessageList & Adopt ( SMessageList & other )

Transfer ownership of messages from argument to this message list.
Messages are merged to this in timestamp order. The other list is empty upon return.

int32_t CountMessages ( uint32_t what = B_ANY_WHAT ) const

Return the total number of messages in the list.
If what is supplied, only messages with that code are counted.

SMessage * DequeueMessage ( uint32_t what = B_ANY_WHAT,

bool * more = NULL

)

Remove the next message from the queue.
If what is specified, this will remove the next message of the specific code; otherwise the next message of any code is removed. If more is supplied, it will be set to true if more messages remain in the list.

void EnqueueMessage ( SMessage * msg )

Place a new message into the queue.
The input msg is added to the linked list (the message takes ownership of the object). The message's timestamp is set to SysGetRunTime() if it does not yet have a time.

SMessage * EnqueueMessageRemoveDups ( const SMessage & msg,

nsecs_t time,

SValue * outPrevData,

SMessageList * outRemoved

)

Like EnqueueMessage(), but first removes all other messages with the same code.
Adds a copy of msg to the list, placed at the given time in the list. Any other messages in the list with the same time stamp are removed and placed in to outRemoved.
Parameters:

[in] msg The message being added, a copy is made to place in the queue.

[in] time Time at which the message should be placed in the queue.

[out] outPrevData If a message in the queue was replaced with this message, this is the data that was in the old message.

[out] outRemoved Filled in with any message objects that were removed from the queue.

Returns:
Address of the message that was placed in the queue.

SMessage * EnqueueUniqueMessage ( const SMessage & msg,

nsecs_t time,

SValue * outPrevData,

SMessageList * outRemoved

)

Like EnqueueMessage(), but ensures the message code is unique in the list.
Adds a copy of msg to the list. The message will be placed either at the time given, or the earliest time for which there currently exists a message with the same code. This is unlike EnueueMessageRemoveDups(), which always returns with the enqueued message having the same timestamp that was passed in.
Parameters:

[in] msg The message being added, a copy is made to place in the queue.

[in] time The oldest time at which the message should be placed in the queue. If there is already a message in the queue with the same code but an earlier time, that time is used instead.

[out] outPrevData If a message in the queue was replaced with this message, this is the data that was in the old message.

[out] outRemoved Filled in with any message objects that were removed from the queue.

Returns:
Address of the message that was placed in the queue.

Note:
If there are messages in the list with the same code but before this one in time, the contents of msg will replace the first of them and take that timestamp instead, removing all others. In this case outPrevData will contain the contents of the previous message.

const SMessage * Head ( ) const

Retrieve first message in the list.

void InsertAfter ( SMessage * message,

const SMessage * position

)

Place the given message immediately after position in the list.
If position is NULL, the message is added to the front of the list (the same as calling AddHead(message)).

void InsertBefore ( SMessage * message,

const SMessage * position

)

Place the given message immediately before position in the list.
If position is NULL, the message is added to the end of the list (the same as calling AddTail(message)).

bool IsEmpty ( ) const

Return true if there are no messages in the list.

void MakeEmpty ( )

Remove all messages from the list, deleting the objects.

const SMessage * Next ( const SMessage * current ) const

Return the next message after current in the list.

nsecs_t OldestMessage ( int32_t * out_priority ) const

Find information about the next message in the list.
Returns the time at which the next message should be executed, and optionally out_priority is filled in with the priority of that message.

const SMessage * Previous ( const SMessage * current ) const

Return the previous message before current in the list.

SMessage * Remove ( const SMessage * message )

Remove the given message from the list and return it.

SMessage * RemoveHead ( )

Remove the first message from the list and return it.

SMessage * RemoveTail ( )

Remove the last message from the list and return it.

const SMessage * Tail ( ) const

Retrieve last message in the list.

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


Public Member Functions
Adding
These are low-level APIs for placing messages into the list.
void	AddHead (SMessage *message)
	Place the given message at the front of the list.
void	AddTail (SMessage *message)
	Place the given message at the end of the list.
void	InsertAfter (SMessage message, const SMessage position)
	Place the given message immediately after position in the list.
void	InsertBefore (SMessage message, const SMessage position)
	Place the given message immediately before position in the list.
Creation and Destruction
SMessageList &	Adopt (SMessageList &other)
	Transfer ownership of messages from argument to this message list.
	SMessageList ()
	Transfer ownership of messages from argument to this message list.
	~SMessageList ()
	Transfer ownership of messages from argument to this message list.
Global Operations
Functionality that manipulates the message list as a whole.
int32_t	CountMessages (uint32_t what=B_ANY_WHAT) const
	Return the total number of messages in the list.
bool	IsEmpty () const
	Return true if there are no messages in the list.
void	MakeEmpty ()
	Remove all messages from the list, deleting the objects.
Queue Operations
These manage the message list as a queue, keeping the messages sorted by their timestamp order.
SMessage *	DequeueMessage (uint32_t what=B_ANY_WHAT, bool *more=NULL)
	Remove the next message from the queue.
void	EnqueueMessage (SMessage *msg)
	Place a new message into the queue.
SMessage *	EnqueueMessageRemoveDups (const SMessage &msg, nsecs_t time, SValue outPrevData, SMessageList outRemoved)
	Like EnqueueMessage(), but first removes all other messages with the same code.
SMessage *	EnqueueUniqueMessage (const SMessage &msg, nsecs_t time, SValue outPrevData, SMessageList outRemoved)
	Like EnqueueMessage(), but ensures the message code is unique in the list.
nsecs_t	OldestMessage (int32_t *out_priority) const
	Find information about the next message in the list.
Iteration
These APIs allow you to step over the linked list of messages.
const SMessage *	Head () const
	Retrieve first message in the list.
const SMessage *	Next (const SMessage *current) const
	Return the next message after current in the list.
const SMessage *	Previous (const SMessage *current) const
	Return the previous message before current in the list.
const SMessage *	Tail () const
	Retrieve last message in the list.
Removing
Low-level APIs for removing messages from the list.
SMessage *	Remove (const SMessage *message)
	Remove the given message from the list and return it.
SMessage *	RemoveHead ()
	Remove the first message from the list and return it.
SMessage *	RemoveTail ()
	Remove the last message from the list and return it.

SMessageList Class Reference [Utility Classes and Functions]

Detailed Description

Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation

SMessageList Class Reference
[Utility Classes and Functions]