| | | Mercury Monitor Reference Manual | |
|---|
ActuatorsActuators — Actuator support functions |
#include <monitor/producer/actuator.h> #define PROD_SYMBOL_ACTUATOR #define PROD_ACTUATOR_MODULE (desc) #define PROD_ACTUATOR_API prod_actuator_module; prod_ctrl_desc; int (*prod_ctrl_execute) (prod_ctrl_instance *ci, mon_ctx *ctx); int prod_actuator_add (prod_actuator_module *actuator, prod_module_type type); int prod_actuator_register (mon_module *module); void prod_actuator_unregister (mon_module *module); void prod_actuator_ref (prod_actuator_module *actuator); void prod_actuator_done (prod_actuator_module *actuator); int prod_actuator_get (mon_metric_def *def, mon_arg_list *arg, mon_module **actuator, uint32_t *actuator_id, mon_ctx *ctx); int prod_actuator_set_priority (prod_actuator_module *actuator, int priority); prod_ctrl_instance; void prod_ctrl_instance_ref (prod_ctrl_instance *ci); prod_ctrl_instance* prod_ctrl_instance_new (prod_actuator_module *actuator, mon_metric_def *def, mon_arg_list *arg, uint32_t actuator_id); void prod_ctrl_instance_done (prod_ctrl_instance *ci); prod_metric_value* prod_ctrl_status_new (prod_ctrl_instance *ci); void prod_ctrl_send_result (prod_ctrl_instance *ci, prod_metric_value *mv); int prod_actuator_check_ctrl (prod_actuator_module *actuator, mon_metric_def *def, mon_arg_list *args, uint32_t *actuator_id, mon_ctx *ctx); int prod_actuator_execute (prod_ctrl_instance *ci, mon_ctx *ctx); int prod_actuator_send_int32 (prod_ctrl_instance *ci, int32_t val); int prod_actuator_send_uint32 (prod_ctrl_instance *ci, uint32_t val); int prod_actuator_send_int64 (prod_ctrl_instance *ci, int64_t val); int prod_actuator_send_uint64 (prod_ctrl_instance *ci, uint64_t val); int prod_actuator_send_string (prod_ctrl_instance *ci, const char *val);
#define PROD_SYMBOL_ACTUATOR MON_MODSYM(prod_module_actuator)
Defines the symbol name of the actuator module descriptor table in a loadable module.
#define PROD_ACTUATOR_MODULE(desc)
Declares an actuator module.
| desc : | name of the prod_actuator_module descriptor. |
#define PROD_ACTUATOR_API 1
Defines the actuator API version implemented by the library.
typedef struct {
mon_module header;
unsigned int priority;
const prod_ctrl_desc *ctrl_table;
const char *ctrl_glob;
int (*check_ctrl)(prod_actuator_module *actuator,
mon_metric_def *def,
mon_arg_list *args,
uint32_t *actuator_idx,
mon_ctx *ctx);
int (*execute)(prod_ctrl_instance *ci,
mon_ctx *ctx);
} prod_actuator_module;
Represents an actuator module.
| mon_module header; | the general module header. |
| unsigned int priority; | priority of the actuator. |
| const prod_ctrl_desc *ctrl_table; | a table containing controls supported by this actuator. This is needed only if the module wants to use prod_actuator_make_ctrl(). |
| const char *ctrl_glob; | a pattern matching all the controls supported by this actuator. This is used by the producer to speed up finding an actuator providing a given control. |
| check_ctrl () | checks that the control definition and parameters are acceptable by the actuator. |
| execute () | method to actually execute a prod_ctrl_instance. |
typedef struct {
const char *name;
prod_ctrl_execute execute;
uint32_t actuator_id;
} prod_ctrl_desc;
Describes a control supported by an actuator.
| const char *name; | the name of the control. |
| prod_ctrl_execute execute; | the execution function. |
| uint32_t actuator_id; | opaque identifier that may be used by the actuator to identify the control. |
int (*prod_ctrl_execute) (prod_ctrl_instance *ci, mon_ctx *ctx);
Executes a prod_ctrl_instance.
| ci : | a prod_ctrl_instance. |
| ctx : | a mon_ctx execution context. |
| Returns : | 0 or MON_CONTINUE on success or an error code. |
int prod_actuator_add (prod_actuator_module *actuator, prod_module_type type);
Registers an actuator module.
| actuator : | a prod_actuator_module. |
| type : | type of the module. |
| Returns : | 0 if successful or an error code. |
int prod_actuator_register (mon_module *module);
Wrapper around prod_actuator_add() to register dynamically loaded actuator modules.
| module : | a mon_module pointing to an actuator module. |
| Returns : | 0 if successful or an error code. |
void prod_actuator_unregister (mon_module *module);
Unregisters an actuator module.
| module : | a mon_module pointing to an actuator module. |
void prod_actuator_ref (prod_actuator_module *actuator);
Increments the reference count of a prod_actuator_module.
| actuator : | a prod_actuator_module. |
void prod_actuator_done (prod_actuator_module *actuator);
Decrements the reference count of a prod_actuator_module. If the reference count reaches zero, the module is deallocated (or unloaded if it was loaded dynamically).
| actuator : | a prod_actuator_module. |
int prod_actuator_get (mon_metric_def *def, mon_arg_list *arg, mon_module **actuator, uint32_t *actuator_id, mon_ctx *ctx);
Initializes an enumeration context for finding an actuator that provides a given control.
| def : | a mon_metric_def control definition. |
| arg : | control arguments. |
| actuator : | pointer to store the actuator module if successful. |
| actuator_id : | pointer to store an opaque internal identifier if successful. |
| ctx : | a mon_ctx execution context. |
| Returns : | 0 if successful or an error code. |
int prod_actuator_set_priority (prod_actuator_module *actuator, int priority);
Sets the priority of a actuator.
| actuator : | a prod_actuator_module. |
| priority : | the new priority of the actuator. |
| Returns : | 0 if successful or an error code. |
typedef struct {
/* Fields controlled by the producer library */
prod_actuator_module *actuator;
mon_metric_def *ctrl;
mon_arg_list *args;
uint32_t actuator_id;
prod_conn *conn;
uint32_t id;
int refcnt;
} prod_ctrl_instance;
Describes a control instance about to be executed.
| prod_actuator_module *actuator; | the prod_actuator_module providing the control. |
| mon_metric_def *ctrl; | the mon_metric_def control definition. |
| mon_arg_list *args; | control arguments. |
| uint32_t actuator_id; | opaque internal identifier returned by the check_ctrl method. |
| prod_conn *conn; | the prod_conn the control execution was requested on. |
| uint32_t id; | the id of the control's response message. |
| int refcnt; | reference count. |
void prod_ctrl_instance_ref (prod_ctrl_instance *ci);
Increments the reference count of a prod_ctrl_instance.
| ci : | a prod_ctrl_instance. |
prod_ctrl_instance* prod_ctrl_instance_new (prod_actuator_module *actuator, mon_metric_def *def, mon_arg_list *arg, uint32_t actuator_id);
Allocates a new prod_ctrl_instance.
| actuator : | prod_actuator_module providing the control. |
| def : | a mon_metric_def. |
| arg : | control arguments. |
| actuator_id : | opaque internal identifier returned by the check_ctrl method. |
| Returns : | a prod_ctrl_instance or NULL if out of memory. |
void prod_ctrl_instance_done (prod_ctrl_instance *ci);
Decrements the reference count of a prod_ctrl_instance. If the reference count reaches zero, the control instance is destroyed.
| ci : | a prod_ctrl_instance. |
prod_metric_value* prod_ctrl_status_new (prod_ctrl_instance *ci);
Allocates a new metric value for holding the control's result.
| ci : | a prod_ctrl_instance. |
| Returns : | a prod_metric_value. |
void prod_ctrl_send_result (prod_ctrl_instance *ci, prod_metric_value *mv);
Sends the result of a control.
| ci : | a prod_ctrl_instance. |
| mv : | a prod_metric_value. |
int prod_actuator_check_ctrl (prod_actuator_module *actuator, mon_metric_def *def, mon_arg_list *args, uint32_t *actuator_id, mon_ctx *ctx);
Checks if an actuator module provides a control by looking it up in the actuator's control table.
| actuator : | a prod_actuator_module. |
| def : | a mon_metric_def. |
| args : | control arguments (not checked by this function). |
| actuator_id : | place to store an opaque identifier that can be used by the actuator to identify the control. |
| ctx : | a mon_ctx execution context. |
| Returns : | 0 if the sensor does provide this control or an error code otherwise. |
int prod_actuator_execute (prod_ctrl_instance *ci, mon_ctx *ctx);
Executes a control instance. This function looks up the actual execution method in the actuator's control table.
| ci : | a prod_ctrl_instance. |
| ctx : | a mon_ctx execution context. |
| Returns : | 0 if successful or an error code. |
int prod_actuator_send_int32 (prod_ctrl_instance *ci, int32_t val);
Sends a 32-bit integer value as the result of the control's execution.
| ci : | a prod_ctrl_instance. |
| val : | the value to send. |
| Returns : | 0 if successful or an error code. |
int prod_actuator_send_uint32 (prod_ctrl_instance *ci, uint32_t val);
Sends a 32-bit unsigned integer value as the result of the control's execution.
| ci : | a prod_ctrl_instance. |
| val : | the value to send. |
| Returns : | 0 if successful or an error code. |
int prod_actuator_send_int64 (prod_ctrl_instance *ci, int64_t val);
Sends a 64-bit integer value as the result of the control's execution.
| ci : | a prod_ctrl_instance. |
| val : | the value to send. |
| Returns : | 0 if successful or an error code. |
int prod_actuator_send_uint64 (prod_ctrl_instance *ci, uint64_t val);
Sends a 64-bit unsigned integer value as the result of the control's execution.
| ci : | a prod_ctrl_instance. |
| val : | the value to send. |
| Returns : | 0 if successful or an error code. |
int prod_actuator_send_string (prod_ctrl_instance *ci, const char *val);
Sends a string value as the result of the control's execution.
| ci : | a prod_ctrl_instance. |
| val : | the value to send. |
| Returns : | 0 if successful or an error code. |
| << Access Control Checking | Command Processing >> |