Functions to allow modules to push resumption frames onto the stack and inform the interpreter about the conditions they need to be resumed under (usually an I/O event or timer event). More...

#include <freeradius-devel/server/module.h>
#include <freeradius-devel/server/module_rlm.h>
#include <freeradius-devel/server/rcode.h>
#include <freeradius-devel/unlang/subrequest.h>
#include <freeradius-devel/unlang/tmpl.h>

Include dependency graph for module.h:

Go to the source code of this file.

Typedefs
typedef void(*	unlang_module_fd_event_t) (module_ctx_t const mctx, request_t request, int fd)
	A callback when the FD is ready for reading. More...

typedef void(*	unlang_module_retry_t) (module_ctx_t const mctx, request_t request, fr_retry_t const *retry)
	A callback when a retry happens. More...

typedef void(*	unlang_module_signal_t) (module_ctx_t const mctx, request_t request, fr_signal_t action)
	A callback when the request gets a fr_signal_t. More...

Functions
int	unlang_module_push (rlm_rcode_t p_result, request_t request, module_instance_t *module_instance, module_method_t method, bool top_frame)
	Push a module or submodule onto the stack for evaluation. More...

void	unlang_module_retry_now (module_ctx_t const mctx, request_t request)
	Run the retry handler. More...

int	unlang_module_set_resume (request_t *request, module_method_t resume)
	Change the resume function of a module. More...

unlang_action_t	unlang_module_yield (request_t request, module_method_t resume, unlang_module_signal_t signal, fr_signal_t sigmask, void rctx)
	Yield a request back to the interpreter from within a module. More...

unlang_action_t	unlang_module_yield_to_retry (request_t request, module_method_t resume, unlang_module_retry_t retry_cb, unlang_module_signal_t signal, fr_signal_t sigmask, void rctx, fr_retry_config_t const *retry_cfg)
	Yield a request back to the interpreter, with retries. More...

unlang_action_t	unlang_module_yield_to_section (rlm_rcode_t p_result, request_t request, CONF_SECTION subcs, rlm_rcode_t default_rcode, module_method_t resume, unlang_module_signal_t signal, fr_signal_t sigmask, void rctx)

unlang_action_t	unlang_module_yield_to_tmpl (TALLOC_CTX ctx, fr_value_box_list_t out, request_t request, tmpl_t const vpt, unlang_tmpl_args_t args, module_method_t resume, unlang_module_signal_t signal, fr_signal_t sigmask, void rctx)
	Push a pre-compiled tmpl and resumption state onto the stack for evaluation. More...

unlang_action_t	unlang_module_yield_to_xlat (TALLOC_CTX ctx, bool p_success, fr_value_box_list_t out, request_t request, xlat_exp_head_t const xlat, module_method_t resume, unlang_module_signal_t signal, fr_signal_t sigmask, void rctx)
	Push a pre-compiled xlat and resumption state onto the stack for evaluation. More...

Detailed Description

Functions to allow modules to push resumption frames onto the stack and inform the interpreter about the conditions they need to be resumed under (usually an I/O event or timer event).

Id: 68b2eee6bf0a6d57a1aa753797553b03fdf389dc

Copyright: 2016-2019 The FreeRADIUS server project

Definition in file module.h.

Typedef Documentation

◆ unlang_module_fd_event_t

typedef void(* unlang_module_fd_event_t) (module_ctx_t const *mctx, request_t *request, int fd)

A callback when the FD is ready for reading.

Used when a module needs to read from an FD. Typically the callback is set, and then the module returns unlang_module_yield().

Note: The callback is automatically removed on unlang_interpret_mark_runnable(), so

Parameters

[in]	mctx	calling context for the module. Contains global, thread-specific, and call-specific data for a module.
[in]	request	the current request.
[in]	fd	the file descriptor.

Definition at line 66 of file module.h.

◆ unlang_module_retry_t

typedef void(* unlang_module_retry_t) (module_ctx_t const *mctx, request_t *request, fr_retry_t const *retry)

A callback when a retry happens.

Used when a module needs wait for an event. Typically the callback is set, and then the module returns unlang_module_yield().

Note: The callback is automatically removed on unlang_interpret_mark_runnable(), i.e. if an event on a registered FD occurs before the timeout event fires.

Parameters

[in]	mctx	calling context for the module. Contains global, thread-specific, and call-specific data for a module.
[in]	request	the request.
[in]	retry	retry status. "now" is in retry->updated

Definition at line 52 of file module.h.

◆ unlang_module_signal_t

typedef void(* unlang_module_signal_t) (module_ctx_t const *mctx, request_t *request, fr_signal_t action)

A callback when the request gets a fr_signal_t.

A module may call unlang_yeild(), but still need to do something on FR_SIGNAL_DUP. If so, it's set here.

Note: The callback is automatically removed on unlang_interpret_mark_runnable().

Parameters

[in]	mctx	calling context for the module. Contains global, thread-specific, and call-specific data for a module.
[in]	request	The current request.
[in]	action	which is signalling the request.

Definition at line 80 of file module.h.

Function Documentation

◆ unlang_module_push()

int unlang_module_push	(	rlm_rcode_t *	p_result,
		request_t *	request,
		module_instance_t *	mi,
		module_method_t	method,
		bool	top_frame
	)

Push a module or submodule onto the stack for evaluation.

Parameters

[out]	p_result	Where to write the result of calling the module.
[in]	request	The current request.
[in]	mi	Instance of the module to call.
[in]	method	to call.
[in]	top_frame	Set to UNLANG_TOP_FRAME if the interpreter should return. Set to UNLANG_SUB_FRAME if the interprer should continue.

Returns

0 on success.
-1 on failure.

Definition at line 53 of file module.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ unlang_module_retry_now()

void unlang_module_retry_now	(	module_ctx_t const *	mctx,
		request_t *	request
	)

Run the retry handler.

Called from an async signal handler.

Definition at line 292 of file module.c.

Here is the call graph for this function:

◆ unlang_module_set_resume()

int unlang_module_set_resume	(	request_t *	request,
		module_method_t	resume
	)

Change the resume function of a module.

Parameters

[in]	request	The current request.
[in]	resume	function to call when the XLAT expansion is complete.

Returns

<0 on error
0 on success

Definition at line 132 of file module.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ unlang_module_yield()

unlang_action_t unlang_module_yield	(	request_t *	request,
		module_method_t	resume,
		unlang_module_signal_t	signal,
		fr_signal_t	sigmask,
		void *	rctx
	)

Yield a request back to the interpreter from within a module.

This passes control of the request back to the unlang interpreter, setting callbacks to execute when the request is 'signalled' asynchronously, or whatever timer or I/O event the module was waiting for occurs.

Note: The module function which calls unlang_module_yield should return control of the C stack to the unlang interpreter immediately after calling unlang_module_yield. A common pattern is to use return unlang_module_yield(...).

Parameters

[in]	request	The current request.
[in]	resume	Called on unlang_interpret_mark_runnable().
[in]	signal	Called on unlang_action().
[in]	sigmask	Set of signals to block.
[in]	rctx	to pass to the callbacks.

Returns

UNLANG_ACTION_YIELD.

Definition at line 419 of file module.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ unlang_module_yield_to_retry()

unlang_action_t unlang_module_yield_to_retry	(	request_t *	request,
		module_method_t	resume,
		unlang_module_retry_t	retry,
		unlang_module_signal_t	signal,
		fr_signal_t	sigmask,
		void *	rctx,
		fr_retry_config_t const *	retry_cfg
	)

Yield a request back to the interpreter, with retries.

This passes control of the request back to the unlang interpreter, setting callbacks to execute when the request is 'signalled' asynchronously, or when the retry timer hits.

Note: The module function which calls unlang_module_yield_to_retry should return control of the C stack to the unlang interpreter immediately after calling unlang_module_yield_to_retry. A common pattern is to use return unlang_module_yield_to_retry(...).

Parameters

[in]	request	The current request.
[in]	resume	Called on unlang_interpret_mark_runnable().
[in]	retry	Called on when a retry timer hits
[in]	signal	Called on unlang_action().
[in]	sigmask	Set of signals to block.
[in]	rctx	to pass to the callbacks.
[in]	retry_cfg	to set up the retries

Returns

UNLANG_ACTION_YIELD on success
UNLANG_ACTION_FAIL on failure

Definition at line 361 of file module.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ unlang_module_yield_to_section()

unlang_action_t unlang_module_yield_to_section	(	rlm_rcode_t *	p_result,
		request_t *	request,
		CONF_SECTION *	subcs,
		rlm_rcode_t	default_rcode,
		module_method_t	resume,
		unlang_module_signal_t	signal,
		fr_signal_t	sigmask,
		void *	rctx
	)

Definition at line 248 of file module.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ unlang_module_yield_to_tmpl()

unlang_action_t unlang_module_yield_to_tmpl	(	TALLOC_CTX *	ctx,
		fr_value_box_list_t *	out,
		request_t *	request,
		tmpl_t const *	vpt,
		unlang_tmpl_args_t *	args,
		module_method_t	resume,
		unlang_module_signal_t	signal,
		fr_signal_t	sigmask,
		void *	rctx
	)

Push a pre-compiled tmpl and resumption state onto the stack for evaluation.

In order to use the async unlang processor the calling module needs to establish a resumption point, as the call to an xlat function may require yielding control back to the interpreter.

To simplify the calling conventions, this function is provided to first push a resumption stack frame for the module, and then push a tmpl stack frame.

After pushing those frames the function updates the stack pointer to jump over the resumption frame and execute the tmpl expansion.

When the tmpl interpreter finishes, and pops the tmpl frame, the unlang interpreter will then call the module resumption frame, allowing the module to continue execution.

Parameters

[in]	ctx	To allocate talloc value boxes and values in.
[out]	out	Where to write the result of the expansion.
[in]	request	The current request.
[in]	vpt	the tmpl to expand
[in]	args	Arguments which control how to evaluate the various types of xlats.
[in]	resume	function to call when the XLAT expansion is complete.
[in]	signal	function to call if a signal is received.
[in]	sigmask	Signals to block.
[in]	rctx	to pass to the resume() and signal() callbacks.

Returns

UNLANG_ACTION_PUSHED_CHILD

Definition at line 228 of file module.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ unlang_module_yield_to_xlat()

unlang_action_t unlang_module_yield_to_xlat	(	TALLOC_CTX *	ctx,
		bool *	p_success,
		fr_value_box_list_t *	out,
		request_t *	request,
		xlat_exp_head_t const *	exp,
		module_method_t	resume,
		unlang_module_signal_t	signal,
		fr_signal_t	sigmask,
		void *	rctx
	)

Push a pre-compiled xlat and resumption state onto the stack for evaluation.

In order to use the async unlang processor the calling module needs to establish a resumption point, as the call to an xlat function may require yielding control back to the interpreter.

To simplify the calling conventions, this function is provided to first push a resumption stack frame for the module, and then push an xlat stack frame.

After pushing those frames the function updates the stack pointer to jump over the resumption frame and execute the xlat interpreter.

When the xlat interpreter finishes, and pops the xlat frame, the unlang interpreter will then call the module resumption frame, allowing the module to continue execution.

Parameters

[in]	ctx	To allocate talloc value boxes and values in.
[out]	p_success	Whether xlat evaluation was successful.
[out]	out	Where to write the result of the expansion.
[in]	request	The current request.
[in]	exp	XLAT expansion to evaluate.
[in]	resume	function to call when the XLAT expansion is complete.
[in]	signal	function to call if a signal is received.
[in]	sigmask	Signals to block.
[in]	rctx	to pass to the resume() and signal() callbacks.

Returns

UNLANG_ACTION_PUSHED_CHILD

Definition at line 181 of file module.c.

Here is the call graph for this function:

Here is the caller graph for this function:

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ unlang_module_fd_event_t

◆ unlang_module_retry_t

◆ unlang_module_signal_t

Function Documentation

◆ unlang_module_push()

◆ unlang_module_retry_now()

◆ unlang_module_set_resume()

◆ unlang_module_yield()

◆ unlang_module_yield_to_retry()

◆ unlang_module_yield_to_section()

◆ unlang_module_yield_to_tmpl()

◆ unlang_module_yield_to_xlat()