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

typedef void(*	unlang_module_timeout_t) (module_ctx_t const mctx, request_t request, fr_time_t fired)
	A callback when the the timeout occurs. More...

Functions
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 rctx, int fd)
	Delete a previously set file descriptor callback. More...

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

int	unlang_module_set_resume (request_t *request, module_method_t resume)
	Change the resume function of a module. 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 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: 929f3725556da79bb51bf820a62180981c06a9d4

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 65 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 79 of file module.h.

◆ unlang_module_timeout_t

typedef void(* unlang_module_timeout_t) (module_ctx_t const *mctx, request_t *request, fr_time_t fired)

A callback when the the timeout occurs.

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]	fired	the time the timeout event actually fired.

Definition at line 51 of file module.h.

Function Documentation

◆ 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_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_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_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:

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ unlang_module_fd_event_t

◆ unlang_module_signal_t

◆ unlang_module_timeout_t

Function Documentation

◆ unlang_module_fd_add()

◆ unlang_module_fd_delete()

◆ unlang_module_push()

◆ unlang_module_set_resume()

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