Defines functions for calling modules asynchronously. More...

#include <freeradius-devel/server/modpriv.h>
#include <freeradius-devel/server/request_data.h>
#include <freeradius-devel/server/rcode.h>
#include <freeradius-devel/unlang/call_env.h>
#include "module_priv.h"
#include "tmpl.h"

Include dependency graph for module.c:

Go to the source code of this file.

Functions
static void	safe_lock (module_instance_t *mi)

static void	safe_unlock (module_instance_t *mi)

static unlang_action_t	unlang_module (rlm_rcode_t p_result, request_t request, unlang_stack_frame_t *frame)

static unlang_action_t	unlang_module_done (rlm_rcode_t p_result, request_t request, unlang_stack_frame_t *frame)
	Cleanup after a module completes.

static void	unlang_module_event_retry_handler (UNUSED fr_event_list_t el, fr_time_t now, void ctx)
	Call the callback registered for a retry event.

void	unlang_module_init (void)

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.

static unlang_action_t	unlang_module_resume (rlm_rcode_t p_result, request_t request, unlang_stack_frame_t *frame)
	Wrapper to call a module's resumption function.

static unlang_action_t	unlang_module_resume_done (rlm_rcode_t p_result, request_t request, unlang_stack_frame_t *frame)
	Cleanup after a yielded module completes.

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

static unlang_action_t	unlang_module_retry_resume (rlm_rcode_t p_result, module_ctx_t const mctx, request_t *request)
	Cancel the retry timer on resume.

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

static void	unlang_module_signal (request_t request, unlang_stack_frame_t frame, fr_signal_t action)
	Send a signal (usually stop) to a request.

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.

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.

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.

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.

Detailed Description

Defines functions for calling modules asynchronously.

Id: 11c4fa9fa3d3d928fdaef2bcfb7e546a8c7cbd0e

Copyright: 2018 The FreeRADIUS server project; 2018 Arran Cudbard-Bell (a.cud.nosp@m.bard.nosp@m.b@fre.nosp@m.erad.nosp@m.ius.o.nosp@m.rg)

Definition in file module.c.

Function Documentation

◆ safe_lock()

static void safe_lock ( module_instance_t * mi )

inlinestatic

Definition at line 446 of file module.c.

Here is the caller graph for this function:

◆ safe_unlock()

static void safe_unlock ( module_instance_t * mi )

inlinestatic

Definition at line 454 of file module.c.

Here is the caller graph for this function:

◆ unlang_module()

static unlang_action_t unlang_module	(	rlm_rcode_t *	p_result,
		request_t *	request,
		unlang_stack_frame_t *	frame
	)

static

Definition at line 740 of file module.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ unlang_module_done()

static unlang_action_t unlang_module_done	(	rlm_rcode_t *	p_result,
		request_t *	request,
		unlang_stack_frame_t *	frame
	)

static

Cleanup after a module completes.

Definition at line 502 of file module.c.

Here is the caller graph for this function:

◆ unlang_module_event_retry_handler()

static void unlang_module_event_retry_handler	(	UNUSED fr_event_list_t *	el,
		fr_time_t	now,
		void *	ctx
	)

static

Call the callback registered for a retry event.

Parameters

[in]	el	the event timer was inserted into.
[in]	now	The current time, as held by the event_list.
[in]	ctx	the stack frame

Definition at line 666 of file module.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ unlang_module_init()

void unlang_module_init ( void )

Definition at line 931 of file module.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ 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_resume()

static unlang_action_t unlang_module_resume	(	rlm_rcode_t *	p_result,
		request_t *	request,
		unlang_stack_frame_t *	frame
	)

static

Wrapper to call a module's resumption function.

This is called after the module first yields, and again after any other yields.

Definition at line 541 of file module.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ unlang_module_resume_done()

static unlang_action_t unlang_module_resume_done	(	rlm_rcode_t *	p_result,
		request_t *	request,
		unlang_stack_frame_t *	frame
	)

static

Cleanup after a yielded module completes.

Definition at line 527 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.

◆ unlang_module_retry_resume()

static unlang_action_t unlang_module_retry_resume	(	rlm_rcode_t *	p_result,
		module_ctx_t const *	mctx,
		request_t *	request
	)

static

Cancel the retry timer on resume.

Definition at line 323 of file module.c.

Here is the call graph for this function:

Here is the caller 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_signal()

static void unlang_module_signal	(	request_t *	request,
		unlang_stack_frame_t *	frame,
		fr_signal_t	action
	)

static

Send a signal (usually stop) to a request.

This is typically called via an "async" action, i.e. an action outside of the normal processing of the request.

If there is no unlang_module_signal_t callback defined, the action is ignored.

Parameters

[in]	request	The current request.
[in]	frame	current stack frame.
[in]	action	to signal.

Definition at line 470 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:

Functions

Detailed Description

Function Documentation

◆ safe_lock()

◆ safe_unlock()

◆ unlang_module()

◆ unlang_module_done()

◆ unlang_module_event_retry_handler()

◆ unlang_module_init()

◆ unlang_module_push()

◆ unlang_module_resume()

◆ unlang_module_resume_done()

◆ unlang_module_retry_now()

◆ unlang_module_retry_resume()

◆ unlang_module_set_resume()

◆ unlang_module_signal()

◆ unlang_module_yield()

◆ unlang_module_yield_to_retry()

◆ unlang_module_yield_to_section()

◆ unlang_module_yield_to_tmpl()

◆ unlang_module_yield_to_xlat()