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_t *	msg_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]	bus	The message bus to attach to
[in]	entry	Message 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]	bus	The message bus from which to detach
[in]	entry	Message 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] bus The 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] msg A 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] msg A 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]	bus	The message bus to post this on
[in]	type	The event type (range: 0…31)
[in]	arg	Optional 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]	entry	The message bus entry
[in]	type	The 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]	entry	The message bus entry
[in]	type	The 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]	bus	The bus to check for, may be NULL
[in]	msg	The 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]	m	The message to post the bus
[in]	bus	The message bus to post the message on

Returns: The number of threads the message was sent to.

Detailed Description

Data Structures

Function Documentation

◆ msg_bus_attach()

◆ msg_bus_detach()

◆ msg_bus_get_entry()

◆ msg_bus_get_sender_pid()

◆ msg_bus_get_type()

◆ msg_bus_init()

◆ msg_bus_post()

◆ msg_bus_subscribe()

◆ msg_bus_unsubscribe()

◆ msg_is_from_bus()

◆ msg_send_bus()