Add a notify-pulse action to a condition
Synopsis:
#include <ha/ham.h>
ham_action_t *ham_action_notify_pulse(
ham_condition_t *chdl,
const char *aname,
int nd,
pid_t topid,
int chid,
int pulsecode,
int value,
unsigned flags);
ham_action_t *ham_action_notify_pulse_node(
ham_condition_t *chdl,
const char *aname,
const char *nodename,
pid_t topid,
int chid,
int pulsecode,
int value,
unsigned flags);
Arguments:
- chdl
- The HAM condition handle to which the action is added.
- aname
- The name of the action to add.
- nd
- (ham_action_notify_pulse() only) The node identifier of the targeted remote
node.
- nodename
- (ham_action_notify_pulse_node() only) The targeted remote HAM.
- topid
- The process ID of the targeted process.
- chid
- The channel ID on which topid is located.
- pulsecode
- The code of the pulse to deliver.
- value
- The value of the pulse to deliver.
- flags
- The flags indicating how the action should be operated. See below.
Description:
These functions add an action to a given condition.
This action will deliver a pulse notification to the
process given in
topid.
The handle (chdl) is obtained either:
- from one of the ham_condition*() functions to add conditions
or:
- by calling any of the ham_condition_handle() functions
to request a handle to a specific condition.
The action is executed when the appropriate condition is
triggered.
The nd specifies the node identifier of the remote
node (or local node) to which the pulse is targeted
The nd specified is the node identifier of the
remote node at the time the call is made.
Note:
Since node identifiers are transient objects, you should obtain the
value for
nd immediately before the call, using
netmgr_strtond()
or another function that converts nodenames into node identifiers.
Use the ham_action_notify_pulse_node() function
when a nodename is used to specify a remote HAM instead of a
node identifier (nd). The ham_action_notify_pulse_node()
function takes as a parameter a fully qualified node name (FQNN)
The pulse in pulsecode with the given
value will be delivered to topid on
the specified channel ID (chid).
Currently the following flags are defined:
- HREARMAFTERRESTART
- Indicates that the action is to be automatically rearmed
after the entity that it belongs to is restarted. By
default, this flag is disabled — actions automatically
get pruned across restarts of the entity. Note that if the
condition that this action belongs to is pruned after a
restart, this action will also be removed, regardless of the
value of this flag.
- HACTIONBREAKONFAIL
- Indicates that if this action were to fail,
and it is part of a list of actions, none of the actions following
this one in the list of actions will be executed.
- HACTIONKEEPONFAIL
- Indicates that the action will be retained even if it
fails. The default behavior is to remove failed actions. Nevertheless
if the condition that this action is associated with is not retained,
the action will get automatically removed.
Users can specify what will be done if an action fails. By adding
action fail actions to a list associated with an action, users
can determine what will be done in the case of an action failure. For
every action that fails, the corresponding action fail list will be
executed. Certain actions (e.g., ham_action_log() and
ham_action_heartbeat_healthy()) never fail. For more details,
refer to the appropriate section in the HAM API reference
for the ham_action_fail_*() calls.
Returns:
A valid ham_action_t or NULL if an error
occurred (errno is set).
Errors:
- EBADF
- Couldn't connect to the HAM.
- EEXIST
- The name provided for the action already exists.
- EINVAL
- The name given in aname is invalid (e.g., it
contains the / character) or is NULL.
The connection to the HAM is invalid. This happens when the
process that opened the connection (using ham_connect()) and
the process that's calling ham_action_notify_pulse()
aren't the same.
- ENAMETOOLONG
- The name given is too long, i.e.
it exceeds _POSIX_PATH_MAX (defined in <limits.h>).
Note that the combined length of an entity/condition/action
name is also limited by _POSIX_PATH_MAX.
- ENOENT
- There's no action of the name aname in a
condition cname defined in an entity ename in the HAM's
current context.
- ENOMEM
- Not enough memory to create a new handle.
In addition to the above errors, the HAM returns any error
it encounters while servicing this request.
Classification:
QNX Neutrino
Safety: |
|
Cancellation point |
No |
Interrupt handler |
No |
Signal handler |
No |
Thread |
Yes |