rcl  master
C API providing common ROS client library functionality.
Classes | Typedefs | Enumerations | Functions
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
 
typedef enum rcl_subscription_event_type_t rcl_subscription_event_type_t
 
typedef struct rmw_event_t rmw_event_t
 rmw struct. More...
 
typedef struct rcl_event_t rcl_event_t
 Structure which encapsulates a ROS QoS event handle. More...
 

Enumerations

enum  rcl_publisher_event_type_t { RCL_PUBLISHER_OFFERED_DEADLINE_MISSED, RCL_PUBLISHER_LIVELINESS_LOST }
 
enum  rcl_subscription_event_type_t { RCL_SUBSCRIPTION_REQUESTED_DEADLINE_MISSED, RCL_SUBSCRIPTION_LIVELINESS_CHANGED }
 

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_trcl_event_get_rmw_handle (const rcl_event_t *event)
 Return the rmw event handle. More...
 

Typedef Documentation

◆ rcl_publisher_event_type_t

◆ rcl_subscription_event_type_t

◆ rmw_event_t

typedef struct rmw_event_t rmw_event_t

rmw struct.

◆ rcl_event_t

typedef struct rcl_event_t rcl_event_t

Structure which encapsulates a ROS QoS event handle.

Enumeration Type Documentation

◆ rcl_publisher_event_type_t

Enumerator
RCL_PUBLISHER_OFFERED_DEADLINE_MISSED 
RCL_PUBLISHER_LIVELINESS_LOST 

◆ rcl_subscription_event_type_t

Enumerator
RCL_SUBSCRIPTION_REQUESTED_DEADLINE_MISSED 
RCL_SUBSCRIPTION_LIVELINESS_CHANGED 

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().

◆ 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]eventpointer to fill
[in]publisherto get events from
[in]event_typeto 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_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]eventpointer to fill
[in]subscriptionto get events from
[in]event_typeto 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_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_handleevent object to take from
[in,out]event_infoevent info object to write taken data into
[in,out]takenboolean flag indicating if an event was taken or not
Returns
RCL_RET_OK if successful, or
RCL_RET_BAD_ALLOC if memory allocation 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]eventto 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]eventpointer to the rcl event
Returns
rmw event handle if successful, otherwise NULL