<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<refentry id="mq_message_t">

<refmeta><refentrytitle>mq_message_t</refentrytitle>
<manvolnum>3</manvolnum></refmeta>

<refnamediv><refname>mq_message_t</refname>
<refpurpose>message data structure</refpurpose>
</refnamediv>

<refsynopsisdiv><synopsis>
#include &lt;cds/msg_queue.h&gt;

typedef struct _mq_message_t {
	void *data;
	int data_len;
	struct _mq_message_t *next;
	destroy_function_f destroy_function;
	enum { 
		message_allocated_with_data, 
		message_holding_data_ptr 
	} allocation_style;
	char data_buf[1];
} mq_message_t;
</synopsis></refsynopsisdiv>

<refsect1><title>Description</title>

<para>Data structure used as basic element in message queue. Pointer to
message data should be obtained by <function>get_message_data</function>.
</para>

<para>There are more possibilities how to allocate message data:
<itemizedlist>
	<listitem><para>explicitly, data buffer is allocated outside of
	<structname>mq_message_t</structname> structure and only pointer to it is stored
	in this structure, see <xref linkend="create_message"/>
	<!-- - in this case the data must be deallocated explicitly--></para></listitem>
	
	<listitem><para>implicitly, data buffer is allocated together with
	<structname>mq_message_t</structname> structure - data must be copied into
	it after structure allocation, see <xref linkend="create_message_ex"/></para></listitem>

	<listitem><para>there is third possibility, that data and message - both -
	are allocated by caller without using
	<function>create_message</function>, <function>create_message_ex</function> and 
	<function>msg_free</function>, see <xref linkend="init_message_ex"/></para>
	</listitem>
</itemizedlist>
</para>

<para>More different data allocation methods are due to more efficiency - less
memory allocation calls and less fragmentation in second case, but more common
and may be simpler for usage in first case.
</para>

<para>Warning: internal implementation of this structure may change, use it only
through existing functions.
</para>
</refsect1>

<refsect1><title>See Also</title>
<para><xref linkend="msg_queue_t"/>
</para>
</refsect1>

</refentry> 

