These operations are used to create and destroy messages. Many of them are, for example, used by device drivers and system call code that has to incorporate a data buffer into an x-kernel message.
Messages that are newly created ``own'' the header stack, and can write into that space efficiently using msgPush. See Section 3.4 for more information about message stacks.
Initializes a message structure with a data length set to zero. The user must provide a pointer to valid memory.
void msgConstructEmpty(Msg *message)
Copies data from a user buffer (buffer) into an uninitialized message structure. The message data area, of size length, is allocated and a copy is performed. This constructor is used when the data buffer already exists. Use msgConstructAllocate when you will not have the opportunity to fill the buffer until after it has been created.
void msgConstructBuffer(Msg *message, void *buffer, int length)
Allocates a data area of size length and associates the area with the uninitialized message structure message. A pointer to the data area is returned. A device driver might use this constructor, handing the pointer to the device as a place to put down an incoming packet.
char *msgConstructAllocate(Msg *message, int length)
The uninitialized message message will refer to the same data as original_msg. No data is copied. See also msgAssign.
void msgConstructCopy(Msg *message, Msg *original_msg)
An uninitialized message structure is constructed with a direct reference to the buffer specified. A function appropriate for freeing the buffer when the message is destroyed must be provided. The msgConstructInplace function is recommended only for limited use, such as within device drivers.
void msgConstructInplace(Msg *message, char *buffer, int length, MsgCIPFreeFunc freefunc)
typedef void *MsgCIPFreeFunc)(void *, int);
Logically frees message. Data portions of the deallocated message are freed if there are no other outstanding references to them.
void msgDestroy(Msg *message)
Allocates a data area of size length and associates the area with the initialized message structure message. This is equivalent to (but can be faster than) doing a msgDestroy to message, followed by a msgConstructAllocate. This function should be used only when message is valid.
char *msgRefresh(Msg *message, int length)
The assignment of msg_2 to msg_1 means that msg_1 will refer to the same data that msg_2 currently points to. No data copying is involved. This is equivalent to doing a msgDestroy to msg_1, followed by a msgConstructCopy. This function should be used only when both messages are valid; copying to an uninitialized structure should be done with msgConstructCopy.
void msgAssign(Msg *msg_1, Msg *msg_2)