msgbus.h File Reference

Messaging abstraction interface. More...

#include <stdbool.h>
#include <stdint.h>
#include <time.h>
#include <eii/utils/config.h>
#include <eii/msgbus/msg_envelope.h>

Go to the source code of this file.

Classes
struct	user_data_t
struct	recv_ctx_t
struct	recv_ctx_set_t

Typedefs
typedef void *	publisher_ctx_t

Functions
void *	msgbus_initialize (config_t *config)
void	msgbus_destroy (void *ctx)
msgbus_ret_t	msgbus_publisher_new (void *ctx, const char *topic, publisher_ctx_t **pub_ctx)
msgbus_ret_t	msgbus_publisher_publish (void *ctx, publisher_ctx_t *pub_ctx, msg_envelope_t *message)
void	msgbus_publisher_destroy (void *ctx, publisher_ctx_t *pub_ctx)
msgbus_ret_t	msgbus_subscriber_new (void *ctx, const char *topic, user_data_t *user_data, recv_ctx_t **subscriber)
void	msgbus_recv_ctx_destroy (void *ctx, recv_ctx_t *recv_ctx)
msgbus_ret_t	msgbus_request (void *ctx, recv_ctx_t *service_ctx, msg_envelope_t *message)
msgbus_ret_t	msgbus_response (void *ctx, recv_ctx_t *service_ctx, msg_envelope_t *message)
msgbus_ret_t	msgbus_service_get (void *ctx, const char *service_name, void *user_data, recv_ctx_t **service_ctx)
msgbus_ret_t	msgbus_service_new (void *ctx, const char *service_name, void *user_data, recv_ctx_t **service_ctx)
msgbus_ret_t	msgbus_recv_wait (void *ctx, recv_ctx_t *recv_ctx, msg_envelope_t **message)
msgbus_ret_t	msgbus_recv_timedwait (void *ctx, recv_ctx_t *recv_ctx, int timeout, msg_envelope_t **message)
msgbus_ret_t	msgbus_recv_nowait (void *ctx, recv_ctx_t *recv_ctx, msg_envelope_t **message)

Detailed Description

Messaging abstraction interface.

Author

Kevin Midkiff kevin.nosp@m..mid.nosp@m.kiff@.nosp@m.inte.nosp@m.l.com

Typedef Documentation

publisher_ctx_t

typedef void* publisher_ctx_t

Publisher context

Function Documentation

msgbus_destroy()

void msgbus_destroy

(

void *

ctx

)

Delete and clean up the message bus.

msgbus_initialize()

void* msgbus_initialize

(

config_t *

config

)

Initialize the message bus.

Note

{The message bus context takes ownership of the config_t object at this point and the caller does not have to free the config object.}

Parameters

config

- Configuration object

Returns

Message bus context, or NULL

msgbus_publisher_destroy()

void msgbus_publisher_destroy	(	void *	ctx,
		publisher_ctx_t *	pub_ctx
	)

Destroy publisher

Parameters

ctx	- Message bus context
pub_ctx	- Publisher context

msgbus_publisher_new()

msgbus_ret_t msgbus_publisher_new	(	void *	ctx,
		const char *	topic,
		publisher_ctx_t **	pub_ctx
	)

Create a new publisher context object.

Note

The get_config_value() method for the configuration will be called to retrieve values needed for the underlying protocol to initialize the context for publishing.

This method is not necessarily thread-safe. Calls to this method should either all be done from the same thread or surrounded by a lock.

Parameters

[in]	ctx	- Message bus context
[out]	pub_ctx	- Publisher context

Returns

msgbus_ret_t

msgbus_publisher_publish()

msgbus_ret_t msgbus_publisher_publish	(	void *	ctx,
		publisher_ctx_t *	pub_ctx,
		msg_envelope_t *	message
	)

Publish a message on the message bus.

Parameters

ctx	- Message bus context
pub_ctx	- Publisher context
message	- Messsage object to publish

Returns

msgbus_ret_t

msgbus_recv_ctx_destroy()

void msgbus_recv_ctx_destroy	(	void *	ctx,
		recv_ctx_t *	recv_ctx
	)

Delete and clean up a service, request, or subscriber context.

Parameters

ctx	- Message bus context
recv_ctx	- Receive context

msgbus_recv_nowait()

msgbus_ret_t msgbus_recv_nowait	(	void *	ctx,
		recv_ctx_t *	recv_ctx,
		msg_envelope_t **	message
	)

Receive a message if available, immediately return if there are no messages available.

Parameters

[in]	ctx	- Message bus context
[in]	recv_ctx	- Receive context
[out]	message	- Received message, NULL if timedout

Returns

msgbus_ret_t, MSG_RECV_NO_MESSAGE if no message is available

msgbus_recv_timedwait()

msgbus_ret_t msgbus_recv_timedwait	(	void *	ctx,
		recv_ctx_t *	recv_ctx,
		int	timeout,
		msg_envelope_t **	message
	)

Receive a message over the message bus, if no message is available wait for the given amount of time for a message to arrive.

Parameters

[in]	ctx	- Message bus context
[in]	recv_ctx	- Receive context
[in]	timeout	- Timeout for waiting to receive a message in milliseconds
[out]	message	- Received message, NULL if timedout

Returns

msgbus_ret_t, MSG_RECV_NO_MESSAGE if no message received

msgbus_recv_wait()

msgbus_ret_t msgbus_recv_wait	(	void *	ctx,
		recv_ctx_t *	recv_ctx,
		msg_envelope_t **	message
	)

Receive a message over the message bus using the given receiving context.

Note

{If a response has already been received for a given request, then a MSG_ERR_ALREADY_RECEIVED will be returned.}

Parameters

[in]	ctx	- Message bus context
[in]	recv_ctx	- Context to use when receiving a message
[out]	message	- Message received (if one exists)

Returns

msgbus_ret_t

msgbus_request()

msgbus_ret_t msgbus_request	(	void *	ctx,
		recv_ctx_t *	service_ctx,
		msg_envelope_t *	message
	)

Issue a request over the message bus.

Parameters

ctx	Message bus context
service_ctx	Service context
message	Request

Returns

msgbus_ret_t

msgbus_response()

msgbus_ret_t msgbus_response	(	void *	ctx,
		recv_ctx_t *	service_ctx,
		msg_envelope_t *	message
	)

Respond to the given request.

Parameters

ctx	- Message bus context
service_ctx	- Service context
message	- Response message

Returns

msgbus_ret_t

msgbus_service_get()

msgbus_ret_t msgbus_service_get	(	void *	ctx,
		const char *	service_name,
		void *	user_data,
		recv_ctx_t **	service_ctx
	)

Create a context to send requests to a service.

Note

This method is not necessarily thread-safe. Calls to this method should either all be done from the same thread or surrounded by a lock.

Parameters

[in]	ctx	- Message bus context
[in]	service_name	- Name of the service
[in]	user_data	- User data
[out]	service_ctx	- Service context
	msgbus_ret_t

msgbus_service_new()

msgbus_ret_t msgbus_service_new	(	void *	ctx,
		const char *	service_name,
		void *	user_data,
		recv_ctx_t **	service_ctx
	)

Create context to receive requests over the message bus.

Note

This method is not necessarily thread-safe. Calls to this method should either all be done from the same thread or surrounded by a lock.

Parameters

[in]	ctx	- Message bus context
[in]	service_name	- Name of the service
[in]	user_data	- User data
[out]	service_ctx	- Service context

Returns

msgbus_ret_t

msgbus_subscriber_new()

msgbus_ret_t msgbus_subscriber_new	(	void *	ctx,
		const char *	topic,
		user_data_t *	user_data,
		recv_ctx_t **	subscriber
	)

Subscribe to the given topic.

Note

This method is not necessarily thread-safe. Calls to this method should either all be done from the same thread or surrounded by a lock.

Parameters

[in]	ctx	- Message bus context
[in]	topic	- Subscription topic string
[in]	user_data	- User data attached to the receive context
[out]	subscriber	- Resulting subscription context

Returns

msgbus_ret_t