axl_bool vortex_alive_enable_check ( VortexConnection conn,
long  check_period,
int  max_unreply_count,
VortexAliveFailure  failure_handler 
)

Allows to enable alive supervision on the provided connection.

The function enables a permanent test every check_period to ensure the connection is working. The check is implemented by a simply request/reply with an unreplied tracking to ensure we detect connection lost even when power failures or network cable unplug.

The function accepts a max_unreply_count which usually is 0 (no unreplied messages accepted) or the amount of unreplied messages we are accepting until calling to failure handler or shutdown the connection.

The failure_handler is optional. If not provided, the alive check will call to shutdown the connection (vortex_connection_shutdown), activating connection on close configured (vortex_connection_set_on_close_full) so close handling is unified on the same place.

However, if failure_handler is defined, the alive check will not shutdown the connection and will call the handler.

Parameters
connThe connection where the check will be enabled.
check_periodThe check period. It is defined in microseconds (1 second == 1000000 microseconds). To check every 20ms a connection pass 20000. It must be > 0, or the function will return axl_false.
max_unreply_countThe maximum amount of unreplied messages we accept. It must be > 0 or the function will return axl_false. If max_unreply_count is reached, the failure is triggered.
failure_handlerOptional handler called when a failure is detected.
Returns
axl_true if the check was properly enabled on the connection, otherwise axl_false is returned.

NOTE: about channel created to do alive tests

In order to implement ALIVE checks, a channel must be created over the provided connection. Until that channel isn't working, ALIVE checkign cannot be implemented.

In this context, if the channel isn't created before (max_unreply_count x check_period), with a minimum value of 3 seconds, ALIVE will trigger a failure too.

References CONN_CTX, vortex_connection_get_data(), vortex_connection_ref(), vortex_connection_set_data_full(), vortex_connection_set_on_close_full(), and vortex_thread_pool_new_event().