Aggregation

Data aggregation. More...

Collaboration diagram for Aggregation:

Data Structures
struct	agg
	Data aggregation. More...
struct	agg_typed
	Data aggregation for a specific type. More...

Macros
#define	AGG_FLAG_ALWAYS_PUBLISH   BIT(0)
	Flag indicating the aggregation will always publish the data, even if no members are updated.
#define	AGG_MEMBER_FLAG_IGNORED   BIT(0)
	Flag indicating the aggregation will not monitor the update of the member.
#define	AGG_MEMBER_FLAG_OPTIONAL   BIT(1)
	Flag indicating the aggregation will not wait for the member to be updated before publishing. However, updates to the member will cold start the aggregation from dormant.
#define	AGG_INITIALIZER(_obj, _name, _period, _min_separation, _watermark, _flag, _publish, _user_data, ...)
	Static initializer for a dataa aggregation. Refer to AGG_DEFINE for detailed parameter descriptions.
#define	AGG_DEFINE(name, period, min_separation, watermark, flag, publish, user_data, ...)
	Define a data aggregation named _name to monitor the update of data. May be specified as static to limit the scope of the aggregation.
#define	AGG_MEMBER(member, ...)
	Specify a member of a struct to be monitored for aggregation. Used in AGG_TYPED_DEFINE.
#define	AGG_DATA_INIT(val, ...)
	Intial value of the data. Used in AGG_TYPED_DEFINE.
#define	AGG_TYPED_DEFINE(_name, _type, _init_val, _period, _min_separation, _watermark, _flag, _publish, _user_data, ...)
	Define a data aggregation named _name to monitor the update of members within a data type. May be specified as static to limit the scope of the aggregation.
#define	AGG_TYPED_UPDATE(agg_typed, type, member, value)
	Update a member of data.

Typedefs
typedef void(*	agg_publish_t) (struct agg *agg, void *user_data)
	Function to publish the data.
typedef void(*	agg_typed_publish_t) (const void *data, void *user_data)
	Function to publish the data.

Functions
void	agg_update (struct agg *agg, int idx)
	Signal the update of a data in aggregation.
void	agg_period_timer_cb (struct k_timer *timer)
	Timer callback function for periodic publishing.
void	agg_early_timer_cb (struct k_timer *timer)
	Timer callback function for tracking minimum separation time.
void	agg_work_cb (struct k_work *work)
	Work callback function for the bottom half of publishing, also used for late publishing.
void	agg_typed_publish (struct agg *agg, void *user_data)
	Publish function for data aggregation.

Detailed Description

Data aggregation.

Macro Definition Documentation

AGG_DATA_INIT

#define AGG_DATA_INIT	(		val,
			... )

#include <nturt/msg/aggregation.h>

Value:

({val, __VA_ARGS__})

Intial value of the data. Used in AGG_TYPED_DEFINE.

Parameters

[in]

val

Initialization list of the data.

Returns

Initial value of the data.

AGG_DEFINE

#define AGG_DEFINE	(		name,
			period,
			min_separation,
			watermark,
			flag,
			publish,
			user_data,
			... )

#include <nturt/msg/aggregation.h>

Value:

  struct agg name =                                                        \
      AGG_INITIALIZER(name, name, period, min_separation, watermark, flag, \
                      publish, user_data, __VA_ARGS__)

Define a data aggregation named _name to monitor the update of data. May be specified as static to limit the scope of the aggregation.

Parameters

[in]	name	Name of the aggregation.
[in]	period	Period of data publishing.
[in]	min_separation	Minimum separation time between two data publishing.
[in]	watermark	Watermark to wait for late-arriving members.
[in]	flag	Flag of the aggregation. If no flag is required, 0 should be specified, and multiple flags can be combined by using the bitwise OR operator (|).
[in]	publish	Function to publish the data, must be of type agg_publish_t.
[in]	user_data	Pointer to custom data for the callback.
[in]	...	Flags of the data to be monitored, where each flag represents a data to be monitored. If the data does not require flag, 0 should be specified. The flags can be combined by using the bitwise OR operator (|).

AGG_FLAG_ALWAYS_PUBLISH

#define AGG_FLAG_ALWAYS_PUBLISH   BIT(0)

#include <nturt/msg/aggregation.h>

Flag indicating the aggregation will always publish the data, even if no members are updated.

AGG_INITIALIZER

#define AGG_INITIALIZER	(		_obj,
			_name,
			_period,
			_min_separation,
			_watermark,
			_flag,
			_publish,
			_user_data,
			... )

#include <nturt/msg/aggregation.h>

Value:

  {                                                                          \
      .name = STRINGIFY(_name),                                              \
      .flag = _flag,                                                         \
      .num_member = NUM_VA_ARGS(__VA_ARGS__) +                               \
                    ZERO_OR_COMPILE_ERROR(NUM_VA_ARGS(__VA_ARGS__) < 32),    \
      .member_flags = (uint8_t[]){__VA_ARGS__},                              \
      .fully_updated = FOR_EACH_IDX(_ARG_FULLY_UPDATED, (|), __VA_ARGS__),   \
                                                                             \
      .period = _period,                                                     \
      .min_separation = _min_separation,                                     \
      .watermark = _watermark,                                               \
      .publish = _publish,                                                   \
      .user_data = _user_data,                                               \
                                                                             \
      .early_timer =                                                         \
          Z_TIMER_INITIALIZER(_obj.early_timer, agg_early_timer_cb, NULL),   \
      .period_timer =                                                        \
          Z_TIMER_INITIALIZER(_obj.period_timer, agg_period_timer_cb, NULL), \
      .work = Z_WORK_DELAYABLE_INITIALIZER(agg_work_cb),                     \
      .updated = 0,                                                          \
  }

Static initializer for a dataa aggregation. Refer to AGG_DEFINE for detailed parameter descriptions.

Parameters

[in]

_obj

Object to be initialized.

AGG_MEMBER

#define AGG_MEMBER	(		member,
			... )

#include <nturt/msg/aggregation.h>

Value:

  (member, (COND_CODE_1(__VA_OPT__(1), (__VA_ARGS__), (0))))

Specify a member of a struct to be monitored for aggregation. Used in AGG_TYPED_DEFINE.

Parameters

[in]	member	Member of the struct to be monitored.
[in]	...	Optional flags of the member, multiple flags can be specified by using the bitwise OR operator (|).

AGG_MEMBER_FLAG_IGNORED

#define AGG_MEMBER_FLAG_IGNORED   BIT(0)

#include <nturt/msg/aggregation.h>

Flag indicating the aggregation will not monitor the update of the member.

AGG_MEMBER_FLAG_OPTIONAL

#define AGG_MEMBER_FLAG_OPTIONAL   BIT(1)

#include <nturt/msg/aggregation.h>

Flag indicating the aggregation will not wait for the member to be updated before publishing. However, updates to the member will cold start the aggregation from dormant.

AGG_TYPED_DEFINE

#define AGG_TYPED_DEFINE	(		_name,
			_type,
			_init_val,
			_period,
			_min_separation,
			_watermark,
			_flag,
			_publish,
			_user_data,
			... )

#include <nturt/msg/aggregation.h>

Value:

  struct agg_typed _name = {                                                   \
      .agg = AGG_INITIALIZER(_name.agg, _name, _period, _min_separation,       \
                             _watermark, _flag, agg_typed_publish, _user_data, \
                             FOR_EACH(_AGG_MEMBER_FLAGS, (, ), __VA_ARGS__)),  \
      .data_size = sizeof(_type),                                              \
      .map =                                                                   \
          (uint8_t[sizeof(_type)]){                                            \
              FOR_EACH_IDX_FIXED_ARG(_AGG_MAP, (, ), _type, __VA_ARGS__),      \
          },                                                                   \
                                                                               \
      .publish = _publish,                                                     \
                                                                               \
      .data = &(_type)__DEBRACKET _init_val,                                   \
      .pub_data = &(_type){},                                                  \
  }

Define a data aggregation named _name to monitor the update of members within a data type. May be specified as static to limit the scope of the aggregation.

Parameters

[in]	_name	Name of the aggregation.
[in]	_type	Data type to be monitored.
[in]	_init_val	Initial value of the data, must be a specified by AGG_DATA_INIT.
[in]	_period	Period of data publishing.
[in]	_min_separation	Minimum separation time between two data publishing.
[in]	_watermark	Watermark to wait for late-arriving members.
[in]	_flag	Flag of the aggregation. If no flag is required, 0
[in]	_publish	Function to publish the data, must be of type agg_typed_publish_t.
[in]	_user_data	Pointer to custom data for the callback.
[in]	...	Members of _type to be monitored, must be specified by AGG_MEMBER.

AGG_TYPED_UPDATE

#define AGG_TYPED_UPDATE	(		agg_typed,
			type,
			member,
			value )

#include <nturt/msg/aggregation.h>

Value:

  do {                                                                     \
    K_SPINLOCK(&(agg_typed)->lock) {                                       \
      int idx = (agg_typed)->map[offsetof(type, member)];                  \
      __ASSERT(idx > 0,                                                    \
               "Members must declared in AGG_TYPED_DEFINE to be updated"); \
      ((type *)(agg_typed)->data)->member = (value);                       \
                                                                           \
      agg_update(&(agg_typed)->agg, idx - 1);                              \
    }                                                                      \
  } while (0)

Update a member of data.

Parameters

[in,out]	agg_typed	Pointer to the data aggregation.
[in]	type	Type of the data, must be the same as the type specified in AGG_TYPED_DEFINE.
[in]	member	Member of the data to be updated, must be listed in AGG_TYPED_DEFINE.
[in]	value	New value of the member.

Typedef Documentation

agg_publish_t

typedef void(* agg_publish_t) (struct agg *agg, void *user_data)

#include <nturt/msg/aggregation.h>

Function to publish the data.

Parameters

[in]	agg	Pointer to the data aggregation.
[in]	user_data	Pointer to custom data for callback functions.

agg_typed_publish_t

typedef void(* agg_typed_publish_t) (const void *data, void *user_data)

#include <nturt/msg/aggregation.h>

Function to publish the data.

Parameters

[in]	data	Pointer to the data to be published.
[in]	user_data	Pointer to custom data for callback functions.

Function Documentation

agg_early_timer_cb()

void agg_early_timer_cb

(

struct k_timer *

timer

)

#include <nturt/msg/aggregation.h>

Timer callback function for tracking minimum separation time.

Parameters

[in,out]

timer

Timer.

Warning

Internal use only.

agg_period_timer_cb()

void agg_period_timer_cb

(

struct k_timer *

timer

)

#include <nturt/msg/aggregation.h>

Timer callback function for periodic publishing.

Parameters

[in,out]

timer

Timer.

Warning

Internal use only.

agg_typed_publish()

void agg_typed_publish	(	struct agg *	agg,
		void *	user_data )

#include <nturt/msg/aggregation.h>

Publish function for data aggregation.

Warning

Internal use only.

agg_update()

void agg_update	(	struct agg *	agg,
		int	idx )

#include <nturt/msg/aggregation.h>

Signal the update of a data in aggregation.

Parameters

[in,out]	agg	Pointer to agg.
[in]	idx	Index of the data that is updated.

agg_work_cb()

void agg_work_cb

(

struct k_work *

work

)

#include <nturt/msg/aggregation.h>

Work callback function for the bottom half of publishing, also used for late publishing.

Parameters

[in,out]

work

Work.

Warning

Internal use only.