event.h File Reference

#include "rcl/client.h"
#include "rcl/macros.h"
#include "rcl/publisher.h"
#include "rcl/service.h"
#include "rcl/subscription.h"
#include "rcl/visibility_control.h"

Include dependency graph for event.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	rcl_event_t
	Structure which encapsulates a ROS QoS event handle. More...

Typedefs
typedef enum rcl_publisher_event_type_t	rcl_publisher_event_type_t
	Enumeration of all of the publisher events that may fire.
typedef enum rcl_subscription_event_type_t	rcl_subscription_event_type_t
	Enumeration of all of the subscription events that may fire.
typedef struct rmw_event_t	rmw_event_t
	rmw struct.
typedef struct rcl_event_t	rcl_event_t
	Structure which encapsulates a ROS QoS event handle.

Enumerations
enum	rcl_publisher_event_type_t { RCL_PUBLISHER_OFFERED_DEADLINE_MISSED, RCL_PUBLISHER_LIVELINESS_LOST, RCL_PUBLISHER_OFFERED_INCOMPATIBLE_QOS }
	Enumeration of all of the publisher events that may fire.
enum	rcl_subscription_event_type_t { RCL_SUBSCRIPTION_REQUESTED_DEADLINE_MISSED, RCL_SUBSCRIPTION_LIVELINESS_CHANGED, RCL_SUBSCRIPTION_REQUESTED_INCOMPATIBLE_QOS, RCL_SUBSCRIPTION_MESSAGE_LOST }
	Enumeration of all of the subscription events that may fire.

Functions
rcl_event_t	rcl_get_zero_initialized_event (void)
	Return a rcl_event_t struct with members set to NULL. More...
rcl_ret_t	rcl_publisher_event_init (rcl_event_t *event, const rcl_publisher_t *publisher, const rcl_publisher_event_type_t event_type)
	Initialize an rcl_event_t with a publisher. More...
rcl_ret_t	rcl_subscription_event_init (rcl_event_t *event, const rcl_subscription_t *subscription, const rcl_subscription_event_type_t event_type)
	Initialize an rcl_event_t with a subscription. More...
rcl_ret_t	rcl_take_event (const rcl_event_t *event, void *event_info)
rcl_ret_t	rcl_event_fini (rcl_event_t *event)
rmw_event_t *	rcl_event_get_rmw_handle (const rcl_event_t *event)
	Return the rmw event handle. More...
bool	rcl_event_is_valid (const rcl_event_t *event)
	Check that the event is valid. More...

Function Documentation

rcl_get_zero_initialized_event()

rcl_event_t rcl_get_zero_initialized_event

(

void

)

Return a rcl_event_t struct with members set to NULL.

Should be called to get a null rcl_event_t before passing to rcl_event_init().

Returns

Zero initialized rcl_event_t.

rcl_publisher_event_init()

rcl_ret_t rcl_publisher_event_init	(	rcl_event_t *	event,
		const rcl_publisher_t *	publisher,
		const rcl_publisher_event_type_t	event_type
	)

Initialize an rcl_event_t with a publisher.

Fill the rcl_event_t with the publisher and desired event_type.

Parameters

[in,out]	event	pointer to fill
[in]	publisher	to get events from
[in]	event_type	to listen for

Returns

RCL_RET_OK if the rcl_event_t is filled, or

RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or

RCL_RET_BAD_ALLOC if allocating memory fails, or

RCL_RET_UNSUPPORTED if event_type is not supported, or

RCL_RET_ERROR if an unspecified error occurs.

rcl_subscription_event_init()

rcl_ret_t rcl_subscription_event_init	(	rcl_event_t *	event,
		const rcl_subscription_t *	subscription,
		const rcl_subscription_event_type_t	event_type
	)

Initialize an rcl_event_t with a subscription.

Fill the rcl_event_t with the subscription and desired event_type.

Parameters

[in,out]	event	pointer to fill
[in]	subscription	to get events from
[in]	event_type	to listen for

Returns

RCL_RET_OK if the rcl_event_t is filled, or

RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or

RCL_RET_BAD_ALLOC if allocating memory fails, or

RCL_RET_UNSUPPORTED if event_type is not supported, or

RCL_RET_ERROR if an unspecified error occurs.

rcl_take_event()

rcl_ret_t rcl_take_event	(	const rcl_event_t *	event,
		void *	event_info
	)

Take an event from the event handle.

Parameters

[in]	event	event object to take from
[in,out]	event_info	event info object to write taken data into

Returns

RCL_RET_OK if successful, or

RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or

RCL_RET_BAD_ALLOC if memory allocation failed, or

RCL_RET_EVENT_TAKE_FAILED if the take event failed, or

RCL_RET_ERROR if an unexpected error occurs.

rcl_event_fini()

rcl_ret_t rcl_event_fini

(

rcl_event_t *

event

)

Finalize an event.

Parameters

[in]

event

to finalize

Returns

RCL_RET_OK if successful, or

RCL_RET_EVENT_INVALID if event is null, or

RCL_RET_ERROR if an unexpected error occurs.

rcl_event_get_rmw_handle()

rmw_event_t* rcl_event_get_rmw_handle

(

const rcl_event_t *

event

)

Return the rmw event handle.

The handle returned is a pointer to the internally held rmw handle. This function can fail, and therefore return NULL, if the:

• event is NULL
• event is invalid (never called init, called fini, or invalid node)

The returned handle is made invalid if the event is finalized or if rcl_shutdown() is called. The returned handle is not guaranteed to be valid for the life time of the event as it may be finalized and recreated itself. Therefore it is recommended to get the handle from the event using this function each time it is needed and avoid use of the handle concurrently with functions that might change it.

---

Attribute	Adherence
Allocates Memory	Yes
Thread-Safe	No
Uses Atomics	No
Lock-Free	Yes

Parameters

[in]

event

pointer to the rcl event

Returns

rmw event handle if successful, otherwise NULL

rcl_event_is_valid()

bool rcl_event_is_valid

(

const rcl_event_t *

event

)

Check that the event is valid.

The bool returned is false if event is invalid. The bool returned is true otherwise. In the case where false is to be returned, an error message is set. This function cannot fail.

---

Attribute	Adherence
Allocates Memory	No
Thread-Safe	No
Uses Atomics	No
Lock-Free	Yes

Parameters

[in]

event

pointer to the rcl event

Returns

true if event is valid, otherwise false