DESCRIPTION

Function is used to add callback handler for LCF command. Command data and callback is configured in cfunc argument structure. The commands for any process may be registered via Enduro/X plugin interface, see ex_devguide(guides).

Limited use of Enduro/X functions within callback

LCF callback are activated at debug log points at any portion of Enduro/X code and also in user code if tplog(3) or TP_LOG() macros are used. Thus it is impossible to guaranty that current XATMI context will be able to do things like tpcall(3), or some UBF buffer manipulations. As callbacks by them selves may be activated from such region. Or from some points where Enduro/X holds mutex locks. That might lead to deadlocks or incorrect/corrupted working further working of the process. To do some XATMI/UBF related works, it is recommended that new thread is started from callback function. Or other option is to set some global variable which later is processed by normal user code.

Following list of functions is safe to use from callbacks:

ndrx_lcf_reg_func_t structure is declared as:

typedef struct
{
    int version;
    int command;
    char cmdstr[NDRX_LCF_ADMINCMD_MAX+1];
    int (*pf_callback)(ndrx_lcf_command_t *cmd, long *p_flags);
} ndrx_lcf_reg_func_t;

Where ndrx_lcf_reg_xadmin_t fields shall be filled in following way:

version - Actual version is present in macros NDRX_LCF_CCMD_VERSION (currently it is 1).

command - This is actual command code. Must be value in range of NDRX_LCF_CMD_MIN_CUST..NDRX_LCF_CMD_MAX_CUST.

cmdstr - Is command string used in xadmin lcf COMMAND. It must be valid C style identifier. Max command string length is 32+1.

pf_callback - Callback function. It receives copy of shared memory command object present in cmd variable. The callback function can return feedback code and feedback message. The values shall be loaded in cmd variable fields (bellow) and corresponding flags NDRX_LCF_FLAG_FBACK_CODE and/or NDRX_LCF_FLAG_FBACK_MSG shall be set. In case of success callback shall return 0 which is accounted in shared memory statistics for given command.

ndrx_lcf_command_t structure is declared as:

typedef struct
{
    int    version;
    unsigned  cmdversion;
    char cmdstr[NDRX_LCF_ADMINCMD_MAX+1];
    ndrx_stopwatch_t publtim;
    int    command;
    char   arg_a[PATH_MAX+1];
    char   arg_b[NAME_MAX+1];
    long   flags;
    char   procid[NAME_MAX];
    int    applied;
    int    failed;
    int    seen;
    long   fbackcode;
    char   fbackmsg[NDRX_LCF_FEEDBACK_BUF];

} ndrx_lcf_command_t;

Where ndrx_lcf_command_t fields is filled in following way:

version - Version number which structure was posted.

cmdversion - Posting number (to detect that command is runnable).

cmdstr - Command string.

publtim - Command age in Enduro/X stopwatch time.

command - Command code published.

arg_a - Argument -A value passed in xadmin lcf COMMAND -A <VALUE>

arg_b - Argument -B value passed in xadmin lcf COMMAND -B <VALUE>

flags - Any NDRX_LCF_FLAG flags. Except NDRX_LCF_FLAG_FBACK_CODE or NDRX_LCF_FLAG_FBACK_MSG.

procid - Pid if flags contains NDRX_LCF_FLAG_PID (posting by pid) or Process name if flags contains NDRX_LCF_FLAG_BIN (posting by binary name). In regexp mode NDRX_LCF_FLAG_DOREX contains regexp expression.

applied - Number of processes applied command, this is up till execution in current binary. NOTE for performance reasons, this value is no synchronized between other processes.

failed - Number of processes failed to execute command, this is up till execution in current binary. NOTE for performance reasons, this value is no synchronized between other processes.

seen - Number of processes seen this command but not matched for execution, this is up till execution in current binary. NOTE for performance reasons, this value is no synchronized between other processes.

fbackcode - this field may be used by callback function to return the value to and store it in shared memory. Value is copied to shm in case if p_flags is set to NDRX_LCF_FLAG_FBACK_CODE. NOTE! value copy is not synchronized between processes and latest process (if several are doing feedback) will survive in results.

fbackmsg - this field may be used by callback function to return the value to and store it in shared memory. Value is copied to shm in case if p_flags is set to NDRX_LCF_FLAG_FBACK_MSG. Buffer size is 64. The data returned must be zero terminated string. NOTE! value copy is not synchronized between processes and latest process (if several are doing feedback) will survive in results.

RETURN VALUE

On success, ndrx_lcf_func_add() returns 0. On error, -1 is returned, with Nerror set to indicate the error.

ERRORS

Note that Nstrerror() returns generic error message plus custom message with debug info from last function call.

NEINVAL cfunc is NULL. cfunc→cmdstr is NULL. cfunc→pf_callback is NULL.

NEVERSION Invalid version specified in structure.

NEEXISTS Callback for command code in cfunc→command is already registered.

NEMALLOC Malloc failed.

THREAD SAFETY

ndrx_lcf_func_add() function is thread safe.

EXAMPLE

See atmitest/test081_lcf/custom_lcf.c for sample code.

BUGS

Report bugs to support@mavimax.com

SEE ALSO

ndrx_lcf_xadmin_add(3) ndrx_lcf_publish(3) ex_devguide(guides) ex_env(5) xadmin(8)

COPYING

© Mavimax, Ltd