Message Queue

group OS_87x3e_Message

Exchange messages between tasks in a FIFO-like operation.

The Message Queue function group allows to control, send, receive, or wait for message. Message transmission is a basic communication model between tasks that one task sends data explicitly, while another task receives it. The operation is more like some kind of I/O rather than a direct access to information to be shared. The data to be passed can be any type.

Defines

os_msg_queue_create(pp_handle, p_name, msg_num, msg_size)

Creates a message queue instance. This allocates the storage required by the new queue and passes back a handle for the queue.

os_msg.h

Example usage

struct test_msg
{
    uint8_t id;
    uint8_t data[16];
}

#define MSG_NUM  10

int test(void)
{
    void *p_handle = NULL;

    // Create a queue capable of containing 10 items of structure test_msg.
    if (os_msg_queue_create(&p_handle, "msg queue name", MSG_NUM, sizeof(struct test_msg)) == true)
    {
        // Message queue created successfully.
    }
    else
    {
        // Message queue failed to create.
        return -1;
    }

    // Delete the message queue.
    os_msg_queue_delete(p_handle);

    return 0;
}

Parameters:

• pp_handle – [out] Used to pass back a handle by which the message queue can be referenced.

• p_name – [in] A descriptive name for the message queue.

• msg_num – [in] The maximum number of items that the queue can contain.

• msg_size – [in] The number of bytes each item in the queue will require. Items are queued by copy, not by reference, so this is the number of bytes that will be copied for each posted item. Each item on the queue must be the same size.

Return values:

• true – Message queue was created successfully.

• false – Message queue was failed to create.

Returns:

The status of the message queue creation.

os_msg_queue_delete(p_handle)

Delete the specified message queue, and free all the memory allocated for storing of items placed on the queue.

os_msg.h

Example usage

struct test_msg
{
    uint8_t id;
    uint8_t data[16];
}

#define MSG_NUM  10

int test(void)
{
    void *p_handle = NULL;

    // Create a queue capable of containing 10 items of structure test_msg.
    if (os_msg_queue_create(&p_handle, "msg queue name", MSG_NUM, sizeof(struct test_msg)) == true)
    {
        // Message queue created successfully.
    }
    else
    {
        // Message queue failed to create.
        return -1;
    }

    // Delete the message queue.
    os_msg_queue_delete(p_handle);

    return 0;
}

Parameters:

• p_handle – [in] The handle to the message queue being deleted.

Return values:

• true – Message queue was deleted successfully.

• false – Message queue was failed to delete.

Returns:

The status of the message queue deletion.

os_msg_queue_peek(p_handle, p_msg_num)

Peek the number of items sent and resided on the message queue.

os_msg.h

Example usage

struct test_msg
{
    uint8_t id;
    uint8_t data[16];
}

#define MSG_NUM  10

int test(void)
{
    void *p_handle = NULL;
    uint32_t msg_num;

    // Create a queue capable of containing 10 items of structure test_msg.
    if (os_msg_queue_create(&p_handle, "msg queue name", MSG_NUM, sizeof(struct test_msg)) == true)
    {
        // Message queue created successfully.
    }
    else
    {
        // Message queue failed to create.
        return -1;
    }

    // Peek the number of items sent on this message queue.
    os_msg_queue_peek(p_handle, &msg_num);

    return 0;
}

Parameters:

• p_handle – [in] The handle to the message queue being peeked.

• p_msg_num – [out] Used to pass back the number of items residing on the message queue.

Return values:

• true – Message queue was peeked successfully.

• false – Message queue was failed to peek.

Returns:

The status of the message queue peek.

os_msg_send(p_handle, p_msg, wait_ms)

Send an item to the back of the specified message queue. The item is queued by copy, not by reference.

os_msg.h

Example usage

struct test_msg
{
    uint8_t id;
    uint8_t data[16];
}

#define MSG_NUM  10

int test(void)
{
    void *p_handle = NULL;
    struct test_msg msg;

    // Create a queue capable of containing 10 items of structure test_msg.
    if (os_msg_queue_create(&p_handle, "msg queue name", MSG_NUM, sizeof(struct test_msg)) == true)
    {
        // Message queue created successfully.
    }
    else
    {
        // Message queue failed to create.
        return -1;
    }

    // Send the item to this message queue.
    msg.id = 1;
    msg.data[0] = 0;
    os_msg_send(p_handle, &msg, 0);

    return 0;
}

Parameters:

• p_handle – [in] The handle to the message queue on which the item is to be sent.

• p_msg – [in] Pointer to the item that is to be sent on the queue. The referenced item rather than pointer itself will be copied on the queue.

• wait_ms – [in] The maximum amount of time in milliseconds that the task should block waiting for the item to sent on the queue.

  • 0 No blocking and return immediately.

  • 0xFFFFFFFF Block infinitely until the item sent.

  • others The timeout value in milliseconds.

Return values:

• true – Message item was sent successfully.

• false – Message item was failed to send.

Returns:

The status of the message item sent.

os_msg_recv(p_handle, p_msg, wait_ms)

Receive an item from the specified message queue. The item is received by copy rather than by reference, so a buffer of adequate size must be provided.

os_msg.h

Example usage

struct test_msg
{
    uint8_t id;
    uint8_t data[16];
}

#define MSG_NUM  10

void *p_handle = NULL;

void send_msg(void)
{
    struct test_msg msg;

    // Create a queue capable of containing 10 items of structure test_msg.
    if (os_msg_queue_create(&p_handle, "msg queue name", MSG_NUM, sizeof(struct test_msg)) == true)
    {
        // Message queue created successfully.
    }
    else
    {
        // Message queue failed to create.
        return -1;
    }

    // Send the item to this message queue.
    msg.id = 1;
    msg.data[0] = 0;
    os_msg_send(p_handle, &msg, 0);

    return 0;
}

void receive_msg(void)
{
    struct test_msg msg;

    // Receive the message queue item.
    if (os_msg_recv(p_handle, &msg, 0) == true)
    {
        // Message item received successfully.
    }
    else
    {
        // Message item failed to receive.
        return -1;
    }

    return 0;
}

Parameters:

• p_handle – [in] The handle to the message queue from which the item is to be received.

• p_msg – [out] Pointer to the buffer into which the received item will be copied. item rather than pointer itself will be copied on the queue.

• wait_ms – [in] The maximum amount of time in milliseconds that the task should block waiting for an item to be received from the queue.

  • 0 No blocking and return immediately.

  • 0xFFFFFFFF Block infinitely until the item received.

  • others The timeout value in milliseconds.

Return values:

• true – Message item was received successfully.

• false – Message item was failed to receive.

Returns:

The status of the message item received.

os_msg_peek(p_handle, p_msg, wait_ms)

Receive but not remove an item from the specified message queue. The item is received by copy rather than by reference, so a buffer of adequate size must be provided.

os_msg.h

Example usage

struct test_msg
{
    uint8_t id;
    uint8_t data[16];
}

#define MSG_NUM  10

void *p_handle = NULL;

void send_msg(void)
{
    struct test_msg msg;

    // Create a queue capable of containing 10 items of structure test_msg.
    if (os_msg_queue_create(&p_handle, "msg queue name", MSG_NUM, sizeof(struct test_msg)) == true)
    {
        // Message queue created successfully.
    }
    else
    {
        // Message queue failed to create.
        return -1;
    }

    // Send the item to this message queue.
    msg.id = 1;
    msg.data[0] = 0;
    os_msg_send(p_handle, &msg, 0);

    return 0;
}

void peek_msg(void)
{
    struct test_msg msg;

    // Peek the message queue item.
    if (os_msg_peek(p_handle, &msg, 0) == true)
    {
        // Message item peeked successfully.
    }
    else
    {
        // Message item failed to peek.
        return -1;
    }

    return 0;
}

Parameters:

• p_handle – [in] The handle to the message queue on which the item is to be peeked.

• p_msg – [out] Pointer to the buffer into which the received item will be copied. item rather than pointer itself will be copied on the queue.

• wait_ms – [in] The maximum amount of time in milliseconds that the task should block waiting for an item to be received from the queue.

  • 0 No blocking and return immediately.

  • 0xFFFFFFFF Block infinitely until the item received.

  • others The timeout value in milliseconds.

Return values:

• true – Message item was received successfully.

• false – Message item was failed to receive.

Returns:

The status of the message item received.