Declarations for the unlang interpreter. More...

#include <freeradius-devel/server/cf_util.h>
#include <freeradius-devel/server/request.h>
#include <freeradius-devel/unlang/action.h>

Include dependency graph for interpret.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	unlang_request_func_t
	External functions provided by the owner of the interpret. More...

Macros
#define	UNLANG_FRAME_PRE_ALLOC (128)
	How much memory we pre-alloc for each frame.

#define	UNLANG_REQUEST_RESUME (false)

#define	UNLANG_REQUEST_RUNNING (true)

#define	UNLANG_STACK_MAX (64)
	The maximum depth of the stack.

#define	UNLANG_SUB_FRAME (false)

#define	UNLANG_TOP_FRAME (true)

Typedefs
typedef struct unlang_interpret_s	unlang_interpret_t
	Interpreter handle.

typedef void(*	unlang_request_done_t) (request_t request, rlm_rcode_t rcode, void uctx)
	Signal the owner of the interpreter that this request completed processing.

typedef void(*	unlang_request_init_t) (request_t request, void uctx)
	Signal the owner of the interpreter that this request should be initialised and executed.

typedef void(*	unlang_request_prioritise_t) (request_t request, void uctx)
	Re-priotise the request in the runnable queue.

typedef void(*	unlang_request_resume_t) (request_t request, void uctx)
	Signal the owner of the interpreter that a request is ready to be resumed.

typedef void(*	unlang_request_runnable_t) (request_t request, void uctx)
	Signal the owner of the interpreter that a request is now runnable.

typedef bool(*	unlang_request_scheduled_t) (request_t const request, void uctx)
	Signal the owner of the interpreter that a request is now runnable.

typedef void(*	unlang_request_stop_t) (request_t request, void uctx)
	Stop a request from running.

typedef void(*	unlang_request_yield_t) (request_t request, void uctx)
	Signal the owner of the interpreter that a request has yielded.

Functions
void	unlang_interpet_frame_discard (request_t *request)
	Discard the bottom most frame on the request's stack.

rlm_rcode_t	unlang_interpret (request_t *request, bool running)
	Run the interpreter for a current request.

fr_event_list_t *	unlang_interpret_event_list (request_t *request)
	Get the event list for the current interpreter.

TALLOC_CTX *	unlang_interpret_frame_talloc_ctx (request_t *request)
	Get a talloc_ctx which is valid only for this frame.

unlang_interpret_t *	unlang_interpret_get (request_t *request)
	Get the interpreter set for a request.

unlang_interpret_t *	unlang_interpret_get_thread_default (void)
	Get the default interpreter for this thread.

unlang_interpret_t *	unlang_interpret_init (TALLOC_CTX ctx, fr_event_list_t el, unlang_request_func_t func, void uctx)
	Initialize a unlang compiler / interpret.

int	unlang_interpret_init_global (TALLOC_CTX *ctx)

bool	unlang_interpret_is_resumable (request_t *request)
	Check if a request as resumable.

void	unlang_interpret_mark_runnable (request_t *request)
	Mark a request as resumable.

int	unlang_interpret_push_instruction (request_t request, void instruction, rlm_rcode_t default_rcode, bool top_frame)
	Push an instruction onto the request stack for later interpretation.

int	unlang_interpret_push_section (request_t request, CONF_SECTION cs, rlm_rcode_t default_action, bool top_frame)
	Push a configuration section onto the request stack for later interpretation.

void	unlang_interpret_request_done (request_t *request)
	Indicate to the caller of the interpreter that this request is complete.

void	unlang_interpret_request_prioritise (request_t *request, uint32_t priority)

void	unlang_interpret_set (request_t request, unlang_interpret_t intp)
	Set a specific interpreter for a request.

void	unlang_interpret_set_thread_default (unlang_interpret_t *intp)
	Set the default interpreter for this thread.

int	unlang_interpret_set_timeout (request_t *request, fr_time_delta_t timeout)
	Set a timeout for a request.

void	unlang_interpret_signal (request_t *request, fr_signal_t action)
	Send a signal (usually stop) to a request.

void *	unlang_interpret_stack_alloc (TALLOC_CTX *ctx)
	Allocate a new unlang stack.

int	unlang_interpret_stack_depth (request_t *request)
	Return the depth of the request's stack.

rlm_rcode_t	unlang_interpret_stack_result (request_t *request)
	Get the current rcode for the frame.

void	unlang_interpret_stack_result_set (request_t *request, rlm_rcode_t code)
	Overwrite the current stack rcode.

rlm_rcode_t	unlang_interpret_synchronous (fr_event_list_t el, request_t request)
	Execute an unlang section synchronously.

bool	unlang_request_is_cancelled (request_t const *request)
	Return whether a request has been cancelled.

bool	unlang_request_is_done (request_t const *request)
	Return whether a request has been marked done.

bool	unlang_request_is_scheduled (request_t const *request)
	Return whether a request is currently scheduled.

Detailed Description

Declarations for the unlang interpreter.

Id: 676652643c5efd0ba1adb6cf64dc6225b9cda3ab

Copyright: 2019 The FreeRADIUS server project

Definition in file interpret.h.

Data Structure Documentation

◆ unlang_request_func_t

struct unlang_request_func_t

External functions provided by the owner of the interpret.

These functions allow the event loop to signal the caller when a given request is ready to run for the first time, and when it should be resumed and passed back to unlang_interpret to continue execution.

This is the cleanest way to separate the interpret and the code that's managing requests.

Test harnesses (for example) need to perform far less initialisation and request management than FeeRADIUS worker threads.

Definition at line 109 of file interpret.h.

Collaboration diagram for unlang_request_func_t:

Data Fields
unlang_request_init_t	detach	Function called when a request is detached.
unlang_request_done_t	done_detached	Function called when a detached request completes.
unlang_request_done_t	done_external	Function called when a external request completes.
unlang_request_done_t	done_internal	Function called when an internal request completes.
unlang_request_init_t	init_internal	Function called to initialise an internal request.
unlang_request_runnable_t	mark_runnable	Function called when a request needs to be added back to the runnable queue.
unlang_request_prioritise_t	prioritise	Function to re-priotise a request in the runnable queue.
unlang_request_resume_t	resume	Function called when a request is resumed.
unlang_request_scheduled_t	scheduled	Function to check if a request is already scheduled.
unlang_request_yield_t	yield	Function called when a request yields.

Macro Definition Documentation

◆ UNLANG_FRAME_PRE_ALLOC

#define UNLANG_FRAME_PRE_ALLOC (128)

How much memory we pre-alloc for each frame.

Definition at line 39 of file interpret.h.

◆ UNLANG_REQUEST_RESUME

#define UNLANG_REQUEST_RESUME (false)

Definition at line 42 of file interpret.h.

◆ UNLANG_REQUEST_RUNNING

#define UNLANG_REQUEST_RUNNING (true)

Definition at line 41 of file interpret.h.

◆ UNLANG_STACK_MAX

#define UNLANG_STACK_MAX (64)

The maximum depth of the stack.

Definition at line 38 of file interpret.h.

◆ UNLANG_SUB_FRAME

#define UNLANG_SUB_FRAME (false)

Definition at line 36 of file interpret.h.

◆ UNLANG_TOP_FRAME

#define UNLANG_TOP_FRAME (true)

Definition at line 35 of file interpret.h.

Typedef Documentation

◆ unlang_interpret_t

typedef struct unlang_interpret_s unlang_interpret_t

Interpreter handle.

Definition at line 47 of file interpret.h.

◆ unlang_request_done_t

typedef void(* unlang_request_done_t) (request_t *request, rlm_rcode_t rcode, void *uctx)

Signal the owner of the interpreter that this request completed processing.

This is called once per request, when the interpret is about to stop processing it.

Definition at line 59 of file interpret.h.

◆ unlang_request_init_t

typedef void(* unlang_request_init_t) (request_t *request, void *uctx)

Signal the owner of the interpreter that this request should be initialised and executed.

This is called once per request, when it's about to start executing.

Definition at line 53 of file interpret.h.

◆ unlang_request_prioritise_t

typedef void(* unlang_request_prioritise_t) (request_t *request, void *uctx)

Re-priotise the request in the runnable queue.

The new priority will be available in request->async->priority.

Definition at line 95 of file interpret.h.

◆ unlang_request_resume_t

typedef void(* unlang_request_resume_t) (request_t *request, void *uctx)

Signal the owner of the interpreter that a request is ready to be resumed.

This is called any time a yielded request has resumed.

Definition at line 77 of file interpret.h.

◆ unlang_request_runnable_t

typedef void(* unlang_request_runnable_t) (request_t *request, void *uctx)

Signal the owner of the interpreter that a request is now runnable.

This is called any time a yielded request has been marked runnable.

Definition at line 83 of file interpret.h.

◆ unlang_request_scheduled_t

typedef bool(* unlang_request_scheduled_t) (request_t const *request, void *uctx)

Signal the owner of the interpreter that a request is now runnable.

This is called any time a yielded request has been marked runnable.

Definition at line 89 of file interpret.h.

◆ unlang_request_stop_t

typedef void(* unlang_request_stop_t) (request_t *request, void *uctx)

Stop a request from running.

This is called whenever a request has been signalled to stop

Definition at line 65 of file interpret.h.

◆ unlang_request_yield_t

typedef void(* unlang_request_yield_t) (request_t *request, void *uctx)

Signal the owner of the interpreter that a request has yielded.

This is called whenever a request has given control back to the interpreter.

Definition at line 71 of file interpret.h.

Function Documentation

◆ unlang_interpet_frame_discard()

void unlang_interpet_frame_discard ( request_t * request )

Discard the bottom most frame on the request's stack.

This is used for cleaning up after errors. i.e. the caller uses a push function, and experiences an error and needs to remove the frame that was just pushed.

Definition at line 1730 of file interpret.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ unlang_interpret()

rlm_rcode_t unlang_interpret	(	request_t *	request,
		bool	running
	)

Run the interpreter for a current request.

This function runs the interpreter for a request. It deals with popping stack frames, and calaculating the final result for the frame.

Parameters

[in]	request	to run. If this is an internal request the request may be freed by the interpreter.
[in]	running	Is the interpreter already running.

Returns: The final request rcode.

Definition at line 712 of file interpret.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ unlang_interpret_event_list()

fr_event_list_t * unlang_interpret_event_list ( request_t * request )

Get the event list for the current interpreter.

Definition at line 1757 of file interpret.c.

Here is the caller graph for this function:

◆ unlang_interpret_frame_talloc_ctx()

TALLOC_CTX * unlang_interpret_frame_talloc_ctx ( request_t * request )

Get a talloc_ctx which is valid only for this frame.

Parameters

[in] request The current request.

Returns

a TALLOC_CTX which is valid only for this stack frame

Definition at line 1405 of file interpret.c.

Here is the caller graph for this function:

◆ unlang_interpret_get()

unlang_interpret_t * unlang_interpret_get ( request_t * request )

Get the interpreter set for a request.

Definition at line 1747 of file interpret.c.

Here is the caller graph for this function:

◆ unlang_interpret_get_thread_default()

unlang_interpret_t * unlang_interpret_get_thread_default ( void )

Get the default interpreter for this thread.

This allows detached requests to be executed asynchronously

Definition at line 1780 of file interpret.c.

Here is the caller graph for this function:

◆ unlang_interpret_init()

unlang_interpret_t * unlang_interpret_init	(	TALLOC_CTX *	ctx,
		fr_event_list_t *	el,
		unlang_request_func_t *	funcs,
		void *	uctx
	)

Initialize a unlang compiler / interpret.

Parameters

[in]	ctx	to bind lifetime of the interpret to. Shouldn't be any free order issues here as the interpret itself has no state. But event loop should be stopped before freeing the interpret.
[in]	el	for any timer or I/O events.
[in]	funcs	Callbacks to used to communicate request state to our owner.
[in]	uctx	Data to pass to callbacks.

Definition at line 1697 of file interpret.c.

Here is the caller graph for this function:

◆ unlang_interpret_init_global()

int unlang_interpret_init_global ( TALLOC_CTX * ctx )

Definition at line 1787 of file interpret.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ unlang_interpret_is_resumable()

bool unlang_interpret_is_resumable ( request_t * request )

Check if a request as resumable.

Parameters

[in] request The current request.

Returns

true if the request is resumable (i.e. has yielded)
false if the request is not resumable (i.e. has not yielded)

Definition at line 1342 of file interpret.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ unlang_interpret_mark_runnable()

void unlang_interpret_mark_runnable ( request_t * request )

Mark a request as resumable.

It's not called "unlang_interpret", because it doesn't actually resume the request, it just schedules it for resumption.

Note: that this schedules the request for resumption. It does not immediately start running the request.

Parameters

[in] request The current request.

Definition at line 1360 of file interpret.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ unlang_interpret_push_instruction()

int unlang_interpret_push_instruction	(	request_t *	request,
		void *	instruction,
		rlm_rcode_t	default_rcode,
		bool	top_frame
	)

Push an instruction onto the request stack for later interpretation.

Definition at line 949 of file interpret.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ unlang_interpret_push_section()

int unlang_interpret_push_section	(	request_t *	request,
		CONF_SECTION *	cs,
		rlm_rcode_t	default_action,
		bool	top_frame
	)

Push a configuration section onto the request stack for later interpretation.

Definition at line 926 of file interpret.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ unlang_interpret_request_done()

void unlang_interpret_request_done ( request_t * request )

Indicate to the caller of the interpreter that this request is complete.

Definition at line 1006 of file interpret.c.

Here is the caller graph for this function:

◆ unlang_interpret_request_prioritise()

void unlang_interpret_request_prioritise	(	request_t *	request,
		uint32_t	priority
	)

Definition at line 1051 of file interpret.c.

Here is the caller graph for this function:

◆ unlang_interpret_set()

void unlang_interpret_set	(	request_t *	request,
		unlang_interpret_t *	intp
	)

Set a specific interpreter for a request.

Definition at line 1738 of file interpret.c.

Here is the caller graph for this function:

◆ unlang_interpret_set_thread_default()

void unlang_interpret_set_thread_default ( unlang_interpret_t * intp )

Set the default interpreter for this thread.

Definition at line 1769 of file interpret.c.

Here is the caller graph for this function:

◆ unlang_interpret_set_timeout()

int unlang_interpret_set_timeout	(	request_t *	request,
		fr_time_delta_t	timeout
	)

Set a timeout for a request.

The timeout is associated with the current stack frame.

Definition at line 1251 of file interpret.c.

Here is the call graph for this function:

◆ unlang_interpret_signal()

void unlang_interpret_signal	(	request_t *	request,
		fr_signal_t	action
	)

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.

Note: This does NOT immediately stop the request, it just deliveres signals, and in the case of a cancel, marks up frames for unwinding and adds it to the runnable queue if it's yielded.; This function should be safe to call anywhere.

Parameters

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

Definition at line 1147 of file interpret.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ unlang_interpret_stack_alloc()

void * unlang_interpret_stack_alloc ( TALLOC_CTX * ctx )

Allocate a new unlang stack.

Parameters

[in] ctx to allocate stack in.

Returns

A new stack on success.
NULL on OOM.

Definition at line 980 of file interpret.c.

Here is the caller graph for this function:

◆ unlang_interpret_stack_depth()

int unlang_interpret_stack_depth ( request_t * request )

Return the depth of the request's stack.

Definition at line 1276 of file interpret.c.

Here is the caller graph for this function:

◆ unlang_interpret_stack_result()

rlm_rcode_t unlang_interpret_stack_result ( request_t * request )

Get the current rcode for the frame.

This can be useful for getting the result of unlang_function_t pushed onto the stack for evaluation.

Parameters

[in] request The current request.

Returns: the current rcode for the frame.

Definition at line 1291 of file interpret.c.

Here is the caller graph for this function:

◆ unlang_interpret_stack_result_set()

void unlang_interpret_stack_result_set	(	request_t *	request,
		rlm_rcode_t	rcode
	)

Overwrite the current stack rcode.

Parameters

[in]	request	The current request.
[in]	rcode	to set.

Definition at line 1303 of file interpret.c.

Here is the caller graph for this function:

◆ unlang_interpret_synchronous()

rlm_rcode_t unlang_interpret_synchronous	(	fr_event_list_t *	el,
		request_t *	request
	)

Execute an unlang section synchronously.

Create a temporary event loop and swap it out for the one in the request. Execute unlang operations until we receive a non-yield return code then return.

Note: The use cases for this are very limited. If you need to use it, chances are what you're doing could be done better using one of the thread event loops.

Parameters

[in]	el	Event list for the temporary interpreter. If NULL a temporary list will be allocated.
[in]	request	The current request.

Returns: One of the RLM_MODULE_* macros.

Definition at line 193 of file interpret_synchronous.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ unlang_request_is_cancelled()

bool unlang_request_is_cancelled ( request_t const * request )

Return whether a request has been cancelled.

Definition at line 1323 of file interpret.c.

Here is the caller graph for this function:

◆ unlang_request_is_done()

bool unlang_request_is_done ( request_t const * request )

Return whether a request has been marked done.

Definition at line 1330 of file interpret.c.

Here is the caller graph for this function:

◆ unlang_request_is_scheduled()

bool unlang_request_is_scheduled ( request_t const * request )

Return whether a request is currently scheduled.

Definition at line 1313 of file interpret.c.

Here is the caller graph for this function:

Data Structures

Macros

Typedefs

Functions

Detailed Description

Data Structure Documentation

◆ unlang_request_func_t

Macro Definition Documentation

◆ UNLANG_FRAME_PRE_ALLOC

◆ UNLANG_REQUEST_RESUME

◆ UNLANG_REQUEST_RUNNING

◆ UNLANG_STACK_MAX

◆ UNLANG_SUB_FRAME

◆ UNLANG_TOP_FRAME

Typedef Documentation

◆ unlang_interpret_t

◆ unlang_request_done_t

◆ unlang_request_init_t

◆ unlang_request_prioritise_t

◆ unlang_request_resume_t

◆ unlang_request_runnable_t

◆ unlang_request_scheduled_t

◆ unlang_request_stop_t

◆ unlang_request_yield_t

Function Documentation

◆ unlang_interpet_frame_discard()

◆ unlang_interpret()

◆ unlang_interpret_event_list()

◆ unlang_interpret_frame_talloc_ctx()

◆ unlang_interpret_get()

◆ unlang_interpret_get_thread_default()

◆ unlang_interpret_init()

◆ unlang_interpret_init_global()

◆ unlang_interpret_is_resumable()

◆ unlang_interpret_mark_runnable()

◆ unlang_interpret_push_instruction()

◆ unlang_interpret_push_section()

◆ unlang_interpret_request_done()

◆ unlang_interpret_request_prioritise()

◆ unlang_interpret_set()

◆ unlang_interpret_set_thread_default()

◆ unlang_interpret_set_timeout()

◆ unlang_interpret_signal()

◆ unlang_interpret_stack_alloc()

◆ unlang_interpret_stack_depth()

◆ unlang_interpret_stack_result()

◆ unlang_interpret_stack_result_set()

◆ unlang_interpret_synchronous()

◆ unlang_request_is_cancelled()

◆ unlang_request_is_done()

◆ unlang_request_is_scheduled()