Message Queue [CDS library - Common Data Structures]

Message queue is a structure useful for sending data between processes. More...

Collaboration diagram for Message Queue:

Data Structures

• struct _mq_message_t

  Structure holding message which can be put into message queue. More...
  

• struct msg_queue

  Message queue structure. More...
  

• typedef struct _mq_message_t mq_message_t

  Structure holding message which can be put into message queue.
  

• typedef struct msg_queue msg_queue_t

  Message queue structure.
  

• mq_message_t * create_message_ex (int data_len)

  The space for data is allocated in messages data (they are automaticaly freed!)! Pointer to allocated data bytes is in data variable in the message structure.
  

• mq_message_t * create_message (void *data, int data_len)

  Creates message holding data allocated using cds_malloc.
  

• void set_data_destroy_function (mq_message_t *msg, destroy_function_f func)

  Sets function which will be called by free_message to destroy data.
  

• void init_message_ex (mq_message_t *m, void *data, int data_len, destroy_function_f func)

  Initializes message.
  

• void free_message (mq_message_t *msg)

  Frees the message and data hold by the message.
  

• int push_message (msg_queue_t *q, mq_message_t *m)

  Put message into queue.
  

• mq_message_t * pop_message (msg_queue_t *q)

  Remove message from queue.
  

• int is_msg_queue_empty (msg_queue_t *q)

  Tests if message queue holds a message.
  

• int msg_queue_init (msg_queue_t *q)

  Initializes message queue with a mutex guarding queue operations.
  

• int msg_queue_init_ex (msg_queue_t *q, int synchronize)

  Initializes message queue.
  

• void msg_queue_init_ref_cnt (msg_queue_t *q, reference_counter_group_t *grp)

  Initializes reference counter for given message queue.
  

• void msg_queue_destroy (msg_queue_t *q)

  Destroys message queue if no more references exist.
  

• void msg_queue_free (msg_queue_t *q)

  Destroys and frees the message queue if no more references exist.
  

• #define MQ_USE_MUTEX   1

  Message queue flag meaning that internal queue mutex is used for synchronization.
  

• #define MQ_USE_REF_CNTR   2

  Message queue flag meaning that reference counters are used.
  

• #define get_message_data(msg)   (msg ? msg->data: NULL)

  Macro for accessing message data.
  

• #define get_message_data_len(msg)   (msg ? msg->data_len: 0)

  Macro for determining message data length.
  

---

Detailed Description

It can be synchronized via its own mutex or the synchronization can be left on caller. It can use reference counter which is useful when accessing dynamicaly allocated queue destroyed by its last user.

Todo:

To meaningfully use reference counters it is needed to add function for adding new reference to message queue.

Todo:

Introduce message types because it is often needed.

---

Define Documentation

#define get_message_data

(

msg

)

(msg ? msg->data: NULL)

It is better to use this macro than accessing internal members of the structure.

Definition at line 119 of file msg_queue.h.

#define get_message_data_len

(

msg

)

(msg ? msg->data_len: 0)

It is better to use this macro than accessing internal members of the structure.

Definition at line 123 of file msg_queue.h.

#define MQ_USE_MUTEX   1

It is set during message queue initialization via msg_queue_init or msg_queue_init_ex.

Definition at line 86 of file msg_queue.h.

Referenced by is_msg_queue_empty(), pop_message(), and push_message().

#define MQ_USE_REF_CNTR   2

To set this flag is needed to call msg_queue_init_ref_cnt with non-NULL group parameter.

Definition at line 91 of file msg_queue.h.

---

Typedef Documentation

typedef struct _mq_message_t mq_message_t

There is a need to allow destroing the message without knowing its internals (destroying message queue with non-processed messages) and thus the destroy_function able to fully destroy whole data hold by message must be given. It is mostly needed to choose the function manually only for complex data with pointers which content need to be freed too. For simple structures it is set automaticaly during the message creation.

typedef struct msg_queue msg_queue_t

Never access its members directly (they may change), always use interface functions!

---

Function Documentation

mq_message_t* create_message	(	void *	data,
		int	data_len
	)

Data must be allocated using cds_malloc or there must be set destroy function via set_data_destroy_function because they are automaticaly freed by free_message!

Definition at line 46 of file msg_queue.c.

References _mq_message_t::allocation_style, cds_malloc, _mq_message_t::data, _mq_message_t::data_len, _mq_message_t::destroy_function, and _mq_message_t::next.

mq_message_t* create_message_ex

(

int

data_len

)

Definition at line 32 of file msg_queue.c.

References _mq_message_t::allocation_style, cds_malloc, _mq_message_t::data, _mq_message_t::data_len, _mq_message_t::destroy_function, and _mq_message_t::next.

void free_message

(

mq_message_t *

msg

)

Definition at line 77 of file msg_queue.c.

References _mq_message_t::allocation_style, cds_free, _mq_message_t::data, and _mq_message_t::destroy_function.

void init_message_ex	(	mq_message_t *	m,
		void *	data,
		int	data_len,
		destroy_function_f	func
	)

If auto_free set, data must be allocated using cds_malloc and are automaticaly freed by free_message (and if msg_queue_destroy called)

Definition at line 60 of file msg_queue.c.

References _mq_message_t::allocation_style, _mq_message_t::data, _mq_message_t::data_len, _mq_message_t::destroy_function, and _mq_message_t::next.

int is_msg_queue_empty

(

msg_queue_t *

q

)

Return values:

	1	if empty
	0	if NOT empty.

Definition at line 142 of file msg_queue.c.

References msg_queue::first, msg_queue::flags, MQ_USE_MUTEX, and msg_queue::q_mutex.

void msg_queue_destroy

(

msg_queue_t *

q

)

This function destroys all message queue internal data but doesn't free the message queue itself. It can be useful for staticaly allocated queues or when allocated not using cds_malloc.

Definition at line 198 of file msg_queue.c.

void msg_queue_free

(

msg_queue_t *

q

)

It uses cds_free for freeing the memory.

Definition at line 203 of file msg_queue.c.

int msg_queue_init

(

msg_queue_t *

q

)

Definition at line 151 of file msg_queue.c.

References msg_queue_init_ex().

Here is the call graph for this function:

int msg_queue_init_ex	(	msg_queue_t *	q,
		int	synchronize
	)

If synchronize is set it initializes a mutex guarding queue operations otherwise the message queue remains unsynchronized.

Definition at line 156 of file msg_queue.c.

References msg_queue::first, msg_queue::flags, msg_queue::last, and msg_queue::q_mutex.

Referenced by msg_queue_init().

Here is the caller graph for this function:

void msg_queue_init_ref_cnt	(	msg_queue_t *	q,
		reference_counter_group_t *	grp
	)

Parameters:

	grp	specifies group of reference counters to use. The message queue will stop using the reference counter if NULL.
	q	specifies the message queue

Definition at line 208 of file msg_queue.c.

References msg_queue::flags, init_reference_counter(), and msg_queue::ref.

Here is the call graph for this function:

mq_message_t* pop_message

(

msg_queue_t *

q

)

Definition at line 122 of file msg_queue.c.

References msg_queue::first, msg_queue::flags, msg_queue::last, MQ_USE_MUTEX, _mq_message_t::next, and msg_queue::q_mutex.

int push_message	(	msg_queue_t *	q,
		mq_message_t *	m
	)

Definition at line 91 of file msg_queue.c.

References msg_queue::first, msg_queue::flags, msg_queue::last, MQ_USE_MUTEX, _mq_message_t::next, and msg_queue::q_mutex.

void set_data_destroy_function	(	mq_message_t *	msg,
		destroy_function_f	func
	)

This function may be useful when a complex structure with pointers is added as data parameter.

Definition at line 72 of file msg_queue.c.

References _mq_message_t::destroy_function.