Constructor/Destructor Operations

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 stack space and can write into that space efficiently using ``msgPush''. See the section on Usage (4.4) for more information about stacks.

msgConstructEmpty

Initializes a message structure with a data length set to zero. The user must provide a pointer to valid memory.

void msgConstructEmpty (Msg* this);

msgConstructBuffer

Copies data from a user buffer into an uninitialized message structure. The message data area is allocated and a copy is performed. This constructor is used when the data buffer already exists. Use msgConstructAllocate when you have the opportunity to fill the buffer after it has been created.

void msgConstructBuffer (Msg* this, char * buf, long len);

msgConstructAllocate

Allocates a data area of size len and associates the area with the uninitialized message structure this. A pointer to the data area is returned in buf. A device driver might use this constructor, handing buf to the device as a place to put down an incoming packet.

void msgConstructAllocate (Msg* this, long len, char ** buf);

msgConstructCopy

The uninitialized message this will refer to the same data as the message another. No data is copied. See also msgAssign.

void msgConstructCopy (Msg* this, Msg * another);

msgAssign

The assignment of one message m to message this means that message this will refer to the same data that as message m currently does. No data copying is involved. This is equivalent to doing a msgDestroy to this, followed by a msgConstructCopy. Therefore, this function should be used only when both messages are valid. Copying to an uninitialized structure should be done with msgConstructCopy.

void msgAssign (Msg* this, Msg* m);

msgConstructInplace

The uninitialized message this 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 (e.g. within device drivers); it might not be compatible with later implementations of the message library that will provide highly efficient buffer management.

void msgConstructInplace (Msg* this, char * buffer, long length, Pfv freefunc);

msgConstructAppend

The uninitialized message this is initialized to prepare for appending data with msgAppend. The message can be used in any message operation, but msgPush will cause additional space to be allocated. A pointer to the beginning of the new message buffer is returned in the buffer parameter.

void msgConstructAppend (Msg* this, long length, char ** buffer)

msgDestroy

Logically frees message this. Data portions of the message deallocated are freed as a result of this function should there be no other outstanding references to them.

void msgDestroy (Msg* this);