pmsg.h File Reference

---

Detailed Description

PDU Messages.

Author:

Raphael Manfredi

Date:

2002-2003

#include <glib.h>

Go to the source code of this file.

Data Structures
struct	pdata
struct	pmsg
Defines
#define	pdata_start(x)   ((x)->d_arena)
#define	pdata_len(x)   ((size_t) ((x)->d_end - (x)->d_arena))
#define	pdata_addref(x)   do { (x)->d_refcnt++; } while (0)
#define	PMSG_PRIO_MASK   0x00ffffff /**< Only lower bits are relevant */
	Only lower bits are relevant.
#define	pmsg_start(x)   ((x)->m_data->d_arena)
#define	pmsg_phys_len(x)   pdata_len((x)->m_data)
#define	pmsg_is_writable(x)   ((x)->m_data->d_refcnt == 1)
#define	pmsg_prio(x)   ((x)->m_prio & PMSG_PRIO_MASK)
#define	pmsg_is_unread(x)   ((x)->m_rptr == (x)->m_data->d_arena)
#define	pmsg_read_base(x)   ((x)->m_rptr)
#define	pmsg_check(x, y)   ((x)->m_check ? (x)->m_check((x), (y)) : TRUE)
#define	PMSG_P_DATA   0 /**< Regular data, lowest priority */
	Regular data, lowest priority.
#define	PMSG_P_CONTROL   1 /**< Control message */
	Control message.
#define	PMSG_P_URGENT   2 /**< Urgent message */
	Urgent message.
#define	PMSG_P_HIGHEST   3 /**< Highest priority */
	Highest priority.
#define	PMSG_PF_EXT   0x80000000 /**< Message block uses extended form */
	Message block uses extended form.
#define	PMSG_PF_SENT   0x40000000 /**< Message was successfully sent */
	Message was successfully sent.
#define	pmsg_is_extended(x)   ((x)->m_prio & PMSG_PF_EXT)
#define	pmsg_was_sent(x)   ((x)->m_prio & PMSG_PF_SENT)
#define	pmsg_mark_sent(x)   do { (x)->m_prio |= PMSG_PF_SENT; } while (0)
Typedefs
typedef void(*	pdata_free_t )(gpointer p, gpointer arg)
	A data buffer, can be shared by several message blocks.
typedef pdata	pdata_t
typedef pmsg	pmsg_t
typedef gboolean(*	pmsg_check_t )(pmsg_t *mb, const struct mqueue *q)
typedef void(*	pmsg_free_t )(pmsg_t *mb, gpointer arg)
Functions
void	pmsg_init (void)
	Allocate internal variables.
void	pmsg_close (void)
	Free internal variables.
gint	pmsg_size (pmsg_t *mb)
	Compute message's size.
pmsg_t *	pmsg_new (gint prio, gconstpointer buf, gint len)
	Create new message from user provided data, which are copied into the allocated data block.
pmsg_t *	pmsg_new_extend (gint prio, gconstpointer buf, gint len, pmsg_free_t free_cb, gpointer arg)
	Like pmsg_new() but returns an extended form with a free routine callback.
pmsg_t *	pmsg_alloc (gint prio, pdata_t *db, gint roff, gint woff)
	Allocate new message using existing data block `db'.
pmsg_t *	pmsg_clone (pmsg_t *mb)
	Shallow cloning of message, result is referencing the same data.
pmsg_t *	pmsg_clone_extend (pmsg_t *mb, pmsg_free_t free_cb, gpointer arg)
	Extended cloning of message, adds a free routine callback.
pmsg_free_t	pmsg_replace_ext (pmsg_t *mb, pmsg_free_t nfree, gpointer narg, gpointer *oarg)
	Replace free routine from an extended message block.
gpointer	pmsg_get_metadata (pmsg_t *mb)
	Get the "meta data" from an extended message block (the argument passed to the embedded free routine).
pmsg_check_t	pmsg_set_check (pmsg_t *mb, pmsg_check_t check)
	Set the pre-send checking routine for the buffer.
void	pmsg_free (pmsg_t *mb)
	Free all message blocks, and decrease ref count on all data buffers.
gint	pmsg_write (pmsg_t *mb, gconstpointer data, gint len)
	Write data at the end of the message.
gint	pmsg_read (pmsg_t *mb, gpointer data, gint len)
	Read data from the message, returning the amount of bytes transferred.
pdata_t *	pdata_new (gint len)
pdata_t *	pdata_allocb (void *buf, gint len, pdata_free_t freecb, gpointer freearg)
	Create an embedded data buffer out of existing arena.
pdata_t *	pdata_allocb_ext (void *buf, gint len, pdata_free_t freecb, gpointer freearg)
	Create an external (arena not embedded) data buffer out of existing arena.
void	pdata_free_nop (gpointer p, gpointer arg)
	This free routine can be used when there is nothing to be freed for the buffer, probably because it was made out of a static buffer.
void	pdata_unref (pdata_t *db)
	Decrease reference count on buffer, and free it when it reaches 0.

---

Define Documentation

#define pdata_addref (  x   )     do { (x)->d_refcnt++; } while (0)

#define pdata_len (  x   )     ((size_t) ((x)->d_end - (x)->d_arena))

#define pdata_start (  x   )     ((x)->d_arena)

#define pmsg_check (  x, y   )     ((x)->m_check ? (x)->m_check((x), (y)) : TRUE)

#define pmsg_is_extended (  x   )     ((x)->m_prio & PMSG_PF_EXT)

#define pmsg_is_unread (  x   )     ((x)->m_rptr == (x)->m_data->d_arena)

#define pmsg_is_writable (  x   )     ((x)->m_data->d_refcnt == 1)

#define pmsg_mark_sent (  x   )     do { (x)->m_prio |= PMSG_PF_SENT; } while (0)

#define PMSG_P_CONTROL   1 /**< Control message */

Control message.

#define PMSG_P_DATA   0 /**< Regular data, lowest priority */

Regular data, lowest priority.

#define PMSG_P_HIGHEST   3 /**< Highest priority */

Highest priority.

#define PMSG_P_URGENT   2 /**< Urgent message */

Urgent message.

#define PMSG_PF_EXT   0x80000000 /**< Message block uses extended form */

Message block uses extended form.

#define PMSG_PF_SENT   0x40000000 /**< Message was successfully sent */

Message was successfully sent.

#define pmsg_phys_len (  x   )     pdata_len((x)->m_data)

#define pmsg_prio (  x   )     ((x)->m_prio & PMSG_PRIO_MASK)

#define PMSG_PRIO_MASK   0x00ffffff /**< Only lower bits are relevant */

Only lower bits are relevant.

#define pmsg_read_base (  x   )     ((x)->m_rptr)

#define pmsg_start (  x   )     ((x)->m_data->d_arena)

#define pmsg_was_sent (  x   )     ((x)->m_prio & PMSG_PF_SENT)

---

Typedef Documentation

typedef void(* pdata_free_t)(gpointer p, gpointer arg)

A data buffer, can be shared by several message blocks. There are two incarnations of a message data block: one where the buffer's arena is contiguous to the header and starts at its end (the header structure has been stolen at the head of the physical data block), and one where the buffer's arena was independently allocated. The free routine, when present, only frees the data part of the data buffer. Naturally, in its embedded form, this is the whole buffer. The first argument to the free routine is the start of the data to free, i.e. it will be the pdata structure in the embedded case, or the arena base in the detached form. The d_embedded[] field is our reliable discriminent: since it is part of the structure, it is necessarily within that structure. Therefore, when d_arena points to it, we know that the data buffer is of the "embedded" kind.

typedef struct pdata pdata_t

typedef gboolean(* pmsg_check_t)(pmsg_t *mb, const struct mqueue *q)

typedef void(* pmsg_free_t)(pmsg_t *mb, gpointer arg)

typedef struct pmsg pmsg_t

---

Function Documentation

pdata_t* pdata_allocb (  void *  buf, gint  len, pdata_free_t  freecb, gpointer  freearg )

Create an embedded data buffer out of existing arena. The optional `freecb' structure supplies the free routine callback to be used to free the arena, with freearg as additional argument.

pdata_t* pdata_allocb_ext (  void *  buf, gint  len, pdata_free_t  freecb, gpointer  freearg )

Create an external (arena not embedded) data buffer out of existing arena. The optional `freecb' structure supplies the free routine callback to be used to free the arena, with freearg as additional argument.

void pdata_free_nop (  gpointer  p, gpointer  arg )

This free routine can be used when there is nothing to be freed for the buffer, probably because it was made out of a static buffer.

pdata_t* pdata_new (  gint  len  )

void pdata_unref (  pdata_t *  db  )

Decrease reference count on buffer, and free it when it reaches 0.

pmsg_t* pmsg_alloc (  gint  prio, pdata_t *  db, gint  roff, gint  woff )

Allocate new message using existing data block `db'. The `roff' and `woff' are used to delimit the start and the end (first unwritten byte) of the message within the data buffer. Returns: new message.

pmsg_t* pmsg_clone (  pmsg_t *  mb  )

Shallow cloning of message, result is referencing the same data.

pmsg_t* pmsg_clone_extend (  pmsg_t *  mb, pmsg_free_t  free_cb, gpointer  arg )

Extended cloning of message, adds a free routine callback.

void pmsg_close (  void   )

Free internal variables.

void pmsg_free (  pmsg_t *  mb  )

Free all message blocks, and decrease ref count on all data buffers.

gpointer pmsg_get_metadata (  pmsg_t *  mb  )

Get the "meta data" from an extended message block (the argument passed to the embedded free routine).

void pmsg_init (  void   )

Allocate internal variables.

pmsg_t* pmsg_new (  gint  prio, gconstpointer  buf, gint  len )

Create new message from user provided data, which are copied into the allocated data block. If no user buffer is provided, an empty message is created and the length is used to size the data block. Returns: a message made of one message block referencing one new data block.

pmsg_t* pmsg_new_extend (  gint  prio, gconstpointer  buf, gint  len, pmsg_free_t  free_cb, gpointer  arg )

Like pmsg_new() but returns an extended form with a free routine callback.

gint pmsg_read (  pmsg_t *  mb, gpointer  data, gint  len )

Read data from the message, returning the amount of bytes transferred.

pmsg_free_t pmsg_replace_ext (  pmsg_t *  mb, pmsg_free_t  nfree, gpointer  narg, gpointer *  oarg )

Replace free routine from an extended message block. The original free routine and its argument are returned. This is used when wrapping an existing extended message and its metadata in another extension structure. Parameters: mb  the extended message block nfree  the new free routine (NULL to cancel) narg  the new argument to pass to the free routine oarg  where the old argument to the free routine is returned. Can be NULL if no return is expected. Returns: the old free routine.

pmsg_check_t pmsg_set_check (  pmsg_t *  mb, pmsg_check_t  check )

Set the pre-send checking routine for the buffer. This routine, if it exists (non-NULL) is called just before enqueueing the message for sending. If it returns FALSE, the message is immediately dropped. The callback routine must not modify the message, as the buffer can be shared among multiple messages, unless its refcount is 1. Returns: the previous pre-send checking routine.

gint pmsg_size (  pmsg_t *  mb  )

Compute message's size.

gint pmsg_write (  pmsg_t *  mb, gconstpointer  data, gint  len )

Write data at the end of the message. The message must be the only reference to the underlying data. Returns: amount of written data.

---