ham_entity_t *ham_attach_self(char *ename, uint64_t hp, int hpdl,
int hpdh, unsigned flags);
int ham_detach_self(ham_entity_t *ehdl, unsigned flags);
You use these two functions to attach/detach a process to/from a HAM as a self-attached entity.
The ename argument represents the symbolic name for this entity, which needs to be unique in the system (of all monitored entities at the instant the call is made).
The hp argument represents time values in nanoseconds for the heartbeat period. Heartbeating can be used to ensure “liveness” of the monitored entity. Liveness is a property that describes a component's useful progress. In many cases, the availability of a system component is compromised not because the component has necessarily died, but because it isn't responding or making any progress. The heartbeating mechanism lets you specify that a component will issue a heartbeat at a given interval, and if it misses a certain number of heartbeats, then that would constitute a heartbeat-missed condition.
The hpdl and hpdh represent the number of heartbeats that can be missed before the conditions heartbeatmissedlow and heartbeatmissedhigh are triggered. The HAM API library registers this request with a HAM and also creates a thread that keeps the connection to a HAM open. If the entity were to abnormally terminate, the connection to the HAM is closed, and the HAM will know that this is an abnormal termination (since ham_detach_self() wasn't called first).
On the other hand, if a HAM were to abnormally fail (extremely unlikely) and the Guardian takes over as the new HAM, the connection to the old HAM will have gone stale. In that case, the Guardian notifies all self-attached entities to reattach. The extra thread mentioned above handles this reattach transparently.
If a connection to a HAM is already open, then ham_attach_self() uses the same connection, but increments the reference count of connections opened by this client. A client that indicates that it will heartbeat at a certain period must call ham_heartbeat() to actually transmit a heartbeat to the HAM.
The library also verifies whether the ename provided by the caller is unique. If it doesn't already exist, then this request is forwarded to a HAM, which also checks it again to avoid any race conditions in creating new entities. The ham_attach_self() returns a generic handle, which can be used to detach the process from the HAM later. Note that this handle is an opaque pointer that's also used to add conditions and actions as shown below.
The ham_detach_self() function is used to close the connection to a HAM. From this point on, the HAM will no longer monitor this process as a self-attached entity. The extra thread is canceled. The ham_detach_self() function takes as an argument the handle returned by ham_attach_self().