4.10.6 mq
Keywords: onyx

Next: 4.10.7 mtx Up: 4.10 Classes Previous: 4.10.5 mem Contents Index
Subsections

- 4.10.6.1 API

##
4.10.6 mq

The mq class implements a simple unidirectional message queue. In addition to putting and getting messages, there are methods that control the ability to get or put. This provides a simple out of band state transition capability.

### 4.10.6.1 API

void mq_new(cw_mq_t *a_mq, cw_mema_t *a_mema, uint32_t a_msg_size):

  Input(s):
    a_mq:
      Pointer to space for a mq.
    a_mema:
      Pointer to a memory allocator to use internally.
    a_msg_size:
      Size (in bytes) of messages used for all subsequent calls to mq_*get() and mq_put().
  Output(s):
    None.
  Exception(s):
    CW_ONYXX_OOM.
  Description:
    Constructor.

void mq_delete(cw_mq_t *a_mq):

  Input(s):
    a_mq:
      Pointer to a mq.
  Output(s):
    None.
  Exception(s):
    None.
  Description:
    Destructor.

bool mq_tryget(cw_mq_t *a_mq, ...):

  Input(s):
    a_mq:
      Pointer to a mq.
    ...:
      Pointer to space to store a message.
  Output(s):
    retval:
      false:
        Success.
      true:
        No messages in the queue, or get is in the stop state.
    *...:
      If retval is false, a message. Otherwise, undefined.
  Exception(s):
    None.
  Description:
    Try to get a message, but return true if none are available.

bool mq_timedget(cw_mq_t *a_mq, const struct timespec *a_timeout, ...):

  Input(s):
    a_mq:
      Pointer to a mq.
    a_timeout:
      Timeout, specified as an absolute time interval.
    ...:
      Pointer to space to store a message.
  Output(s):
    retval:
      false:
        Success.
      true:
        No messages in the queue, or get is in the stop state.
    *...:
      If retval is false, a message. Otherwise, undefined.
  Exception(s):
    None.
  Description:
    Get a message. If none are available, block until a message is available, or until timeout.

cw_bol_t mq_get(cw_mq_t *a_mq, ...):

  Input(s):
    a_mq:
      Pointer to a mq.
    ...:
      Pointer to space to store a message.
  Output(s):
    retval:
      false:
        Success.
      true:
        Get is in the stop state.
    *...:
      If retval is false, a message. Otherwise, undefined.
  Exception(s):
    None.
  Description:
    Get a message. If none are available, block until a message is available.

bool mq_put(cw_mq_t *a_mq, ...):

  Input(s):
    a_mq:
      Pointer to a mq.
    ...:
      A message.
  Output(s):
    retval:
      false:
        Success.
      true:
        Failure due to put being in the stop state.
  Exception(s):
    CW_ONYXX_OOM.
  Description:
    Put a message in a_mq.

bool mq_get_start(cw_mq_t *a_mq):

  Input(s):
    a_mq:
      Pointer to a mq.
  Output(s):
    retval:
      false:
        Success.
      true:
        Error (already in start state).
  Exception(s):
    None.
  Description:
    Change the get operation to the start state ( mq_get() will not return true).

bool mq_get_stop(cw_mq_t *a_mq):

  Input(s):
    a_mq:
      Pointer to a mq.
  Output(s):
    retval:
      false:
        Success.
      true:
        Error (already in stop state).
  Exception(s):
    None.
  Description:
    Change the get operation to the stop state ( mq_get() will return true).

bool mq_put_start(cw_mq_t *a_mq):

  Input(s):
    a_mq:
      Pointer to a mq.
  Output(s):
    retval:
      false:
        Success.
      true:
        Error (already in start state).
  Exception(s):
    None.
  Description:
    Change the put operation to the start state ( mq_put() will not return true).

bool mq_put_stop(cw_mq_t *a_mq):

  Input(s):
    a_mq:
      Pointer to a mq.
  Output(s):
    retval:
      false:
        Success.
      true:
        Error (already in stop state).
  Exception(s):
    None.
  Description:
    Change the put operation to the stop state ( mq_put() will return true).

Next: 4.10.7 mtx Up: 4.10 Classes Previous: 4.10.5 mem Contents Index