From 75984389d346445a9bef561a0d8b46f281cde2fe Mon Sep 17 00:00:00 2001 From: =?utf8?q?J=C3=A9r=C3=A9mie=20Galarneau?= Date: Tue, 1 Aug 2017 14:52:57 -0400 Subject: [PATCH 1/1] Docs: document the trigger API MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Signed-off-by: Jérémie Galarneau --- include/lttng/trigger/trigger.h | 50 ++++++++++++++++++++++++++++++++- 1 file changed, 49 insertions(+), 1 deletion(-) diff --git a/include/lttng/trigger/trigger.h b/include/lttng/trigger/trigger.h index b2eab0e3d..0c67abb0b 100644 --- a/include/lttng/trigger/trigger.h +++ b/include/lttng/trigger/trigger.h @@ -31,20 +31,68 @@ enum lttng_register_trigger_status { LTTNG_REGISTER_TRIGGER_STATUS_INVALID = -1, }; -/* The caller retains the ownership of both condition and action. */ +/* + * Create a trigger object associating a condition and an action. + * + * A trigger associates a condition and an action to take whenever the + * condition evaluates to true. Such actions can, for example, consist + * in the emission of a notification to clients listening through + * notification channels. + * + * The caller retains the ownership of both the condition and action + * and both must be kept alive for the lifetime of the trigger object. + * + * A trigger must be registered in order to become activate and can + * be destroyed after its registration. + * + * Returns a trigger object on success, NULL on error. + * Trigger objects must be destroyed using the lttng_trigger_destroy() + * function. + */ extern struct lttng_trigger *lttng_trigger_create( struct lttng_condition *condition, struct lttng_action *action); +/* + * Get the condition of a trigger. + * + * The caller acquires no ownership of the returned condition. + * + * Returns a condition on success, NULL on error. + */ extern struct lttng_condition *lttng_trigger_get_condition( struct lttng_trigger *trigger); +/* + * Get the action of a trigger. + * + * The caller acquires no ownership of the returned action. + * + * Returns an action on success, NULL on error. + */ extern struct lttng_action *lttng_trigger_get_action( struct lttng_trigger *trigger); +/* + * Destroy (frees) a trigger object. + */ extern void lttng_trigger_destroy(struct lttng_trigger *trigger); +/* + * Register a trigger to the session daemon. + * + * The trigger can be destroyed after this call. + * + * Return 0 on success, a negative LTTng error code on error. + */ extern int lttng_register_trigger(struct lttng_trigger *trigger); +/* + * Unregister a trigger from the session daemon. + * + * The trigger can be destroyed after this call. + * + * Return 0 on success, a negative LTTng error code on error. + */ extern int lttng_unregister_trigger(struct lttng_trigger *trigger); #ifdef __cplusplus -- 2.34.1