SMessageList Class Reference
[Utility Classes and Functions]

#include <support/MessageList.h>

List of all members.


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
SMessageListAdopt (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.

SMessageDequeueMessage (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.
SMessageEnqueueMessageRemoveDups (const SMessage &msg, nsecs_t time, SValue *outPrevData, SMessageList *outRemoved)
 Like EnqueueMessage(), but first removes all other messages with the same code.
SMessageEnqueueUniqueMessage (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 SMessageHead () const
 Retrieve first message in the list.
const SMessageNext (const SMessage *current) const
 Return the next message after current in the list.
const SMessagePrevious (const SMessage *current) const
 Return the previous message before current in the list.
const SMessageTail () const
 Retrieve last message in the list.
Removing
Low-level APIs for removing messages from the list.

SMessageRemove (const SMessage *message)
 Remove the given message from the list and return it.
SMessageRemoveHead ()
 Remove the first message from the list and return it.
SMessageRemoveTail ()
 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: