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 "subrequest_priv.h"
#include "tmpl.h"

Include dependency graph for module.c:

Go to the source code of this file.

Data Structures
struct	unlang_module_event_t
	Wrap an fr_event_timer_t providing data needed for unlang events. More...

Functions
static int	_unlang_event_free (unlang_module_event_t *ev)
	Frees an unlang event, removing it from the request's event loop. More...

static void	safe_lock (module_instance_t *mi)

static void	safe_unlock (module_instance_t *mi)

static void	unlang_event_fd_error_handler (UNUSED fr_event_list_t el, int fd, UNUSED int flags, UNUSED int fd_errno, void ctx)
	Call the callback registered for an I/O error event. More...

static void	unlang_event_fd_read_handler (UNUSED fr_event_list_t el, int fd, UNUSED int flags, void ctx)
	Call the callback registered for a read I/O event. More...

static void	unlang_event_fd_write_handler (UNUSED fr_event_list_t el, int fd, UNUSED int flags, void ctx)
	Call the callback registered for a write I/O event. More...

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. More...

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. More...

static void	unlang_module_event_timeout_handler (UNUSED fr_event_list_t el, fr_time_t now, void ctx)
	Call the callback registered for a timeout event. More...

int	unlang_module_fd_add (request_t request, unlang_module_fd_event_t read, unlang_module_fd_event_t write, unlang_module_fd_event_t error, void const rctx, int fd)
	Set a callback for the request. More...

int	unlang_module_fd_delete (request_t request, void const ctx, int fd)
	Delete a previously set file descriptor callback. More...

void	unlang_module_init (void)

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...

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. More...

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. More...

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

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. More...

int	unlang_module_timeout_add (request_t request, unlang_module_timeout_t callback, void const rctx, fr_time_t when)
	Set a timeout for the request. More...

int	unlang_module_timeout_delete (request_t request, void const ctx)
	Delete a previously set timeout callback. 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_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 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. More...

Detailed Description

Defines functions for calling modules asynchronously.

Id: 929ecbc1efe3216dcb2d65570e0c360b5e752739

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.

Data Structure Documentation

◆ unlang_module_event_t

struct unlang_module_event_t

Wrap an fr_event_timer_t providing data needed for unlang events.

Definition at line 42 of file module.c.

Collaboration diagram for unlang_module_event_t:

Data Fields
dl_module_inst_t *	dl_inst	Module instance to pass to callbacks. Use dl_inst->data to get instance data.
void *	env_data	Per call environment data.
fr_event_timer_t const *	ev	Event in this worker's event heap.
int	fd	File descriptor to wait on.
unlang_module_fd_event_t	fd_error	Function to call when FD has errored.
unlang_module_fd_event_t	fd_read	Function to call when FD is readable.
unlang_module_fd_event_t	fd_write	Function to call when FD is writable.
void const *	rctx	rctx data to pass to callbacks.
request_t *	request	Request this event pertains to.
void *	thread	Thread specific module instance.
unlang_module_timeout_t	timeout	Function to call on timeout.

Function Documentation

◆ _unlang_event_free()

static int _unlang_event_free ( unlang_module_event_t * ev )

static

Frees an unlang event, removing it from the request's event loop.

Parameters

[in] ev The event to free.

Returns: 0

Definition at line 81 of file module.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ safe_lock()

static void safe_lock ( module_instance_t * mi )

inlinestatic

Definition at line 602 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 610 of file module.c.

Here is the caller graph for this function:

◆ unlang_event_fd_error_handler()

static void unlang_event_fd_error_handler	(	UNUSED fr_event_list_t *	el,
		int	fd,
		UNUSED int	flags,
		UNUSED int	fd_errno,
		void *	ctx
	)

static

Call the callback registered for an I/O error event.

Parameters

[in]	el	containing the event (not passed to the callback).
[in]	fd	the I/O event occurred on.
[in]	flags	from kevent.
[in]	fd_errno	from kevent.
[in]	ctx	unlang_module_event_t structure holding callbacks.

Definition at line 210 of file module.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ unlang_event_fd_read_handler()

static void unlang_event_fd_read_handler	(	UNUSED fr_event_list_t *	el,
		int	fd,
		UNUSED int	flags,
		void *	ctx
	)

static

Call the callback registered for a read I/O event.

Parameters

[in]	el	containing the event (not passed to the callback).
[in]	fd	the I/O event occurred on.
[in]	flags	from kevent.
[in]	ctx	unlang_module_event_t structure holding callbacks.

Definition at line 66 of file module.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ unlang_event_fd_write_handler()

static void unlang_event_fd_write_handler	(	UNUSED fr_event_list_t *	el,
		int	fd,
		UNUSED int	flags,
		void *	ctx
	)

static

Call the callback registered for a write I/O event.

Parameters

[in]	el	containing the event (not passed to the callback).
[in]	fd	the I/O event occurred on.
[in]	flags	from kevent.
[in]	ctx	unlang_module_event_t structure holding callbacks.

Definition at line 194 of file module.c.

Here is the call graph for this function:

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 876 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 658 of file module.c.

Here is the call graph for this function:

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 822 of file module.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ unlang_module_event_timeout_handler()

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

static

Call the callback registered for a timeout event.

Parameters

[in]	el	the event timer was inserted into.
[in]	now	The current time, as held by the event_list.
[in]	ctx	unlang_module_event_t structure holding callbacks.

Definition at line 105 of file module.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ unlang_module_fd_add()

int unlang_module_fd_add	(	request_t *	request,
		unlang_module_fd_event_t	read,
		unlang_module_fd_event_t	write,
		unlang_module_fd_event_t	error,
		void const *	rctx,
		int	fd
	)

Set a callback for the request.

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().

Parameters

[in]	request	The current request.
[in]	read	callback. Used for receiving and demuxing/decoding data.
[in]	write	callback. Used for writing and encoding data. Where a 3rd party library is used, this should be the function issuing queries, and writing data to the socket. This should not be done in the module itself. This allows write operations to be retried in some instances, and means if the write buffer is full, the request is kept in a suspended state.
[in]	error	callback. If the fd enters an error state. Should cleanup any handles wrapping the file descriptor, and any outstanding requests.
[in]	rctx	for the callback.
[in]	fd	to watch.

Returns

0 on success.
<0 on error.

Definition at line 245 of file module.c.

Here is the call graph for this function:

◆ unlang_module_fd_delete()

int unlang_module_fd_delete	(	request_t *	request,
		void const *	ctx,
		int	fd
	)

Delete a previously set file descriptor callback.

param[in] request the request param[in] fd the file descriptor

Returns

0 on success.
<0 on error.

Definition at line 302 of file module.c.

Here is the call graph for this function:

◆ unlang_module_init()

void unlang_module_init ( void )

Definition at line 1067 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 *	module_instance,
		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]	module_instance	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 325 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 697 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 683 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 400 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 626 of file module.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ unlang_module_timeout_add()

int unlang_module_timeout_add	(	request_t *	request,
		unlang_module_timeout_t	callback,
		void const *	rctx,
		fr_time_t	when
	)

Set a timeout for the request.

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().

param[in] request the current request. param[in] callback to call. param[in] rctx to pass to the callback. param[in] timeout when to call the timeout (i.e. now + timeout).

Returns

0 on success.
<0 on error.

Definition at line 128 of file module.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ unlang_module_timeout_delete()

int unlang_module_timeout_delete	(	request_t *	request,
		void const *	ctx
	)

Delete a previously set timeout callback.

Parameters

[in]	request	The current request.
[in]	ctx	a local context for the callback.

Returns

-1 on error.
0 on success.

Definition at line 176 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 575 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 516 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 496 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 449 of file module.c.

Here is the call graph for this function:

Here is the caller graph for this function:

Data Structures

Functions

Detailed Description

Data Structure Documentation

◆ unlang_module_event_t

Function Documentation

◆ _unlang_event_free()

◆ safe_lock()

◆ safe_unlock()

◆ unlang_event_fd_error_handler()

◆ unlang_event_fd_read_handler()

◆ unlang_event_fd_write_handler()

◆ unlang_module()

◆ unlang_module_done()

◆ unlang_module_event_retry_handler()

◆ unlang_module_event_timeout_handler()

◆ unlang_module_fd_add()

◆ unlang_module_fd_delete()

◆ unlang_module_init()

◆ unlang_module_push()

◆ unlang_module_resume()

◆ unlang_module_resume_done()

◆ unlang_module_set_resume()

◆ unlang_module_signal()

◆ unlang_module_timeout_add()

◆ unlang_module_timeout_delete()

◆ unlang_module_yield()

◆ unlang_module_yield_to_section()

◆ unlang_module_yield_to_tmpl()

◆ unlang_module_yield_to_xlat()