msg_bus.h File Reference

Messaging Bus API for inter process message broadcast. More...

Detailed Description

Messaging Bus API for inter process message broadcast.

Warning
This feature is experimental!
         Threads can subscribe to messages on one or multiple buses.
         If a message is posted on one bus, all threads that are
         subscribed to that message type will receive the message.

         On one bus only 32 different message types are possible.
         Do not use the `type` and `sender_pid` fields of a message
         directly if it may have been received over a message bus.
         Instead, use the @ref msg_bus_get_type and
         @ref msg_bus_get_sender_pid functions.

         If you want to check if a message was sent directly (not
         over a bus, you can use the @ref msg_is_from_bus function.

         @note Make sure to unsubscribe from all previously subscribed
         buses before terminating a thread.
Author
Benjamin Valentin benja.nosp@m.min..nosp@m.valen.nosp@m.tin@.nosp@m.ml-pa.nosp@m..com

Definition in file msg_bus.h.

#include <assert.h>
#include <stdint.h>
#include "list.h"
#include "msg.h"
+ Include dependency graph for msg_bus.h:

Go to the source code of this file.

Data Structures

struct  msg_bus_t
 A message bus is just a list of subscribers. More...
 
struct  msg_bus_entry_t
 Message bus subscriber entry. More...
 
#define MSB_BUS_PID_FLAG   (1U << ((8 * sizeof(kernel_pid_t)) - 1))
 Flag set on sender_pid of msg_t that indicates that the message was sent over a bus.
 
void msg_bus_init (msg_bus_t *bus)
 Initialize a message bus. More...
 
static uint16_t msg_bus_get_type (const msg_t *msg)
 Get the message type of a message bus message. More...
 
static kernel_pid_t msg_bus_get_sender_pid (const msg_t *msg)
 Get the sender PID of a message bus message. More...
 
static bool msg_is_from_bus (const msg_bus_t *bus, const msg_t *msg)
 Check if a message originates from a bus. More...
 
void msg_bus_attach (msg_bus_t *bus, msg_bus_entry_t *entry)
 Attach a thread to a message bus. More...
 
void msg_bus_detach (msg_bus_t *bus, msg_bus_entry_t *entry)
 Remove a thread from a message bus. More...
 
msg_bus_entry_tmsg_bus_get_entry (msg_bus_t *bus)
 Get the message bus entry for the current thread. More...
 
static void msg_bus_subscribe (msg_bus_entry_t *entry, uint8_t type)
 Subscribe to an event on the message bus. More...
 
static void msg_bus_unsubscribe (msg_bus_entry_t *entry, uint8_t type)
 Unsubscribe from an event on the message bus. More...
 
int msg_send_bus (msg_t *m, msg_bus_t *bus)
 Post a pre-assembled message to a bus. More...
 
static int msg_bus_post (msg_bus_t *bus, uint8_t type, const void *arg)
 Post a message to a bus. More...
 

Function Documentation

◆ msg_bus_attach()

void msg_bus_attach ( msg_bus_t bus,
msg_bus_entry_t entry 
)

Attach a thread to a message bus.

This attaches a message bus subscriber entry to a message bus. Subscribe to events on the bus using msg_bus_detach. The thread will then receive events with a matching type that are posted on the bus.

Events can be received with msg_receive. The contents of the received message must not be modified.

Parameters
[in]busThe message bus to attach to
[in]entryMessage bus subscriber entry

◆ msg_bus_detach()

void msg_bus_detach ( msg_bus_t bus,
msg_bus_entry_t entry 
)

Remove a thread from a message bus.

This removes the calling thread from the message bus.

Note
Call this function before the thread terminates.
Parameters
[in]busThe message bus from which to detach
[in]entryMessage bus subscriber entry

◆ msg_bus_get_entry()

msg_bus_entry_t* msg_bus_get_entry ( msg_bus_t bus)

Get the message bus entry for the current thread.

Traverse the message bus to find the subscriber entry for the current thread.

Parameters
[in]busThe message bus to search
Returns
The subscriber entry for the current thread. NULL if the thread is not attached to bus.

◆ msg_bus_get_sender_pid()

static kernel_pid_t msg_bus_get_sender_pid ( const msg_t msg)
inlinestatic

Get the sender PID of a message bus message.

The sender_pid field of themsg_t has a flag bit set to indicate the message was sent over a bus, thus it should not be used directly.

Parameters
[in]msgA message that was received over a bus
Returns
The sender pid

Definition at line 120 of file msg_bus.h.

◆ msg_bus_get_type()

static uint16_t msg_bus_get_type ( const msg_t msg)
inlinestatic

Get the message type of a message bus message.

The type field of themsg_t also encodes the message bus ID, so use this function to get the real 5 bit message type.

If the message was not sent over a bus, this will return the original message ID.

Parameters
[in]msgA message that was received over a bus
Returns
The message type

Definition at line 100 of file msg_bus.h.

◆ msg_bus_init()

void msg_bus_init ( msg_bus_t bus)

Initialize a message bus.

Must be called by the owner of a msg_bus_t struct.

Message buses are considered to be long-running and must be created before any threads can attach to them.

There can be a maximum number of 2047 buses in total.

◆ msg_bus_post()

static int msg_bus_post ( msg_bus_t bus,
uint8_t  type,
const void *  arg 
)
inlinestatic

Post a message to a bus.

This function sends a message to all threads listening on the bus which are listening for messages of type.

It is safe to call this function from interrupt context.

Parameters
[in]busThe message bus to post this on
[in]typeThe event type (range: 0…31)
[in]argOptional event parameter
Returns
The number of threads the event was posted to.

Definition at line 250 of file msg_bus.h.

◆ msg_bus_subscribe()

static void msg_bus_subscribe ( msg_bus_entry_t entry,
uint8_t  type 
)
inlinestatic

Subscribe to an event on the message bus.

Precondition
The entry has been attached to a bus with msg_bus_attach.
Parameters
[in]entryThe message bus entry
[in]typeThe event type to subscribe to (range: 0…31)

Definition at line 198 of file msg_bus.h.

◆ msg_bus_unsubscribe()

static void msg_bus_unsubscribe ( msg_bus_entry_t entry,
uint8_t  type 
)
inlinestatic

Unsubscribe from an event on the message bus.

Precondition
The entry has been attached to a bus with msg_bus_attach.
Parameters
[in]entryThe message bus entry
[in]typeThe event type to unsubscribe (range: 0…31)

Definition at line 212 of file msg_bus.h.

◆ msg_is_from_bus()

static bool msg_is_from_bus ( const msg_bus_t bus,
const msg_t msg 
)
inlinestatic

Check if a message originates from a bus.

If a thread is attached to multiple buses, this function can be used to determine if a message originated from a certain bus.

Parameters
[in]busThe bus to check for, may be NULL
[in]msgThe received message
Returns
True if the messages m was sent over bus If bus is NULL, this function returns true if the message was sent over any bus. False if the messages m was a direct message or from a different bus.

Definition at line 140 of file msg_bus.h.

◆ msg_send_bus()

int msg_send_bus ( msg_t m,
msg_bus_t bus 
)

Post a pre-assembled message to a bus.

This function sends a message to all threads listening on the bus which are listening for messages with the message type of m.

It behaves identical to msg_bus_post, but sends a pre-defined message.

Note
The message is expected to have the event ID encoded in the lower 5 bits and the bus ID encoded in the upper 11 bits of the message type.
Parameters
[in]mThe message to post the bus
[in]busThe message bus to post the message on
Returns
The number of threads the message was sent to.