The FreeRADIUS server $Id: 15bac2a4c627c01d1aa2047687b3418955ac7f00 $
Loading...
Searching...
No Matches
interpret.h
Go to the documentation of this file.
1#pragma once
2/*
3 * This program is free software; you can redistribute it and/or modify
4 * it under the terms of the GNU General Public License as published by
5 * the Free Software Foundation; either version 2, or (at your option)
6 * any later version.
7 *
8 * This program is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 * GNU General Public License for more details.
12 *
13 * You should have received a copy of the GNU General Public License
14 * along with this program; if not, write to the Free Software Foundation,
15 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
16 */
17
18/**
19 * $Id: 6899e970ecf2a111c63868614743ac8e3ae0516f $
20 *
21 * @file unlang/interpret.h
22 * @brief Declarations for the unlang interpreter.
23 *
24 * @copyright 2019 The FreeRADIUS server project
25 */
26
27#ifdef __cplusplus
28extern "C" {
29#endif
30
31#include <freeradius-devel/server/cf_util.h>
32#include <freeradius-devel/server/request.h>
33#include <freeradius-devel/unlang/mod_action.h>
34#include <freeradius-devel/unlang/action.h>
35
36#define UNLANG_TOP_FRAME (true)
37#define UNLANG_SUB_FRAME (false)
38
39#define UNLANG_STACK_MAX (64) //!< The maximum depth of the stack.
40#define UNLANG_FRAME_PRE_ALLOC (128) //!< How much memory we pre-alloc for each frame.
41
42#define UNLANG_REQUEST_RUNNING (true)
43#define UNLANG_REQUEST_RESUME (false)
44
45/** Interpreter handle
46 *
47 */
49
50/** Signal the owner of the interpreter that this request should be initialised and executed
51 *
52 * This is called once per request, when it's about to start executing.
53 */
54typedef void (*unlang_request_init_t)(request_t *request, void *uctx);
55
56/** Signal the owner of the interpreter that this request completed processing
57 *
58 * This is called once per request, when the interpret is about to stop processing it.
59 */
60typedef void (*unlang_request_done_t)(request_t *request, rlm_rcode_t rcode, void *uctx);
61
62/** Stop a request from running
63 *
64 * This is called whenever a request has been signalled to stop
65 */
66typedef void (*unlang_request_stop_t)(request_t *request, void *uctx);
67
68/** Signal the owner of the interpreter that a request has yielded
69 *
70 * This is called whenever a request has given control back to the interpreter.
71 */
72typedef void (*unlang_request_yield_t)(request_t *request, void *uctx);
73
74/** Signal the owner of the interpreter that a request is ready to be resumed
75 *
76 * This is called any time a yielded request has resumed.
77 */
78typedef void (*unlang_request_resume_t)(request_t *request, void *uctx);
79
80/** Signal the owner of the interpreter that a request is now runnable
81 *
82 * This is called any time a yielded request has been marked runnable.
83 */
84typedef void (*unlang_request_runnable_t)(request_t *request, void *uctx);
85
86/** Signal the owner of the interpreter that a request is now runnable
87 *
88 * This is called any time a yielded request has been marked runnable.
89 */
90typedef bool (*unlang_request_scheduled_t)(request_t const *request, void *uctx);
91
92/** Re-priotise the request in the runnable queue
93 *
94 * The new priority will be available in request->async->priority.
95 */
96typedef void (*unlang_request_prioritise_t)(request_t *request, void *uctx);
97
98/** External functions provided by the owner of the interpret
99 *
100 * These functions allow the event loop to signal the caller when a given
101 * request is ready to run for the first time, and when it should be resumed
102 * and passed back to #unlang_interpret to continue execution.
103 *
104 * This is the cleanest way to separate the interpret and the code that's
105 * managing requests.
106 *
107 * Test harnesses (for example) need to perform far less initialisation and
108 * request management than FeeRADIUS worker threads.
109 */
110typedef struct {
111 /*
112 * There's no init_external as this is done
113 * before the external request is handed off
114 * to the interpreter.
115 */
116 unlang_request_init_t init_internal; //!< Function called to initialise an internal request.
117
118 unlang_request_done_t done_external; //!< Function called when a external request completes.
119 unlang_request_done_t done_internal; //!< Function called when an internal request completes.
120 unlang_request_done_t done_detached; //!< Function called when a detached request completes.
121
122 unlang_request_init_t detach; //!< Function called when a request is detached.
123 unlang_request_yield_t yield; //!< Function called when a request yields.
124 unlang_request_resume_t resume; //!< Function called when a request is resumed.
125 unlang_request_runnable_t mark_runnable; //!< Function called when a request needs to be
126 ///< added back to the runnable queue.
127 unlang_request_scheduled_t scheduled; //!< Function to check if a request is already
128 ///< scheduled.
129 unlang_request_prioritise_t prioritise; //!< Function to re-priotise a request in the
130 ///< runnable queue.
132
133typedef struct {
134 rlm_rcode_t rcode; //!< The current rcode, from executing the instruction
135 ///< or merging the result from a frame.
136 unlang_mod_action_t priority; //!< The priority or action for that rcode.
138
139/** Configuration structure to make it easier to pass configuration options to initialise the frame with
140 */
141typedef struct {
142 bool top_frame; //!< Is this the top frame?
143 rlm_rcode_t default_rcode; //!< The default return code for the frame.
144 ///< This needs to be specified separately
145 ///< from p_result, because we may be passing
146 ///< in NULL for p_result.
147 unlang_mod_action_t default_priority; //!< The default priority for the frame.
148 ///< This needs to be specified separately
149 ///< from p_result, because we may be passing
150 ///< in NULL for p_result.
152
153#define FRAME_CONF(_default_rcode, _top_frame) \
154 &(unlang_frame_conf_t){ \
155 .top_frame = (_top_frame), \
156 .default_rcode = (_default_rcode), \
157 .default_priority = MOD_ACTION_NOT_SET \
158 }
159
160#define FRAME_CONF_NO_RCODE(_default_rcode, _top_frame) \
161 &(unlang_frame_conf_t){ \
162 .top_frame = (_top_frame), \
163 .default_rcode = (_default_rcode), \
164 .default_priority = MOD_ACTION_NOT_SET \
165 }
166
167
170 CC_HINT(warn_unused_result);
171
173 void *instruction, unlang_frame_conf_t const *conf)
174 CC_HINT(warn_unused_result);
175
177 fr_event_list_t *el, unlang_request_func_t *func, void *uctx);
178
180
182
184
186
188
190
191int unlang_interpret_set_timeout(request_t *request, fr_time_delta_t timeout) CC_HINT(nonnull);
192
193rlm_rcode_t unlang_interpret(request_t *request, bool running) CC_HINT(hot);
194
196
197void *unlang_interpret_stack_alloc(TALLOC_CTX *ctx);
198
199bool unlang_request_is_scheduled(request_t const *request);
200
201bool unlang_request_is_cancelled(request_t const *request);
202
203bool unlang_request_is_done(request_t const *request);
204
206
208
210
212
213void unlang_interpret_signal(request_t *request, fr_signal_t action);
214
216
218
220
222
223TALLOC_CTX *unlang_interpret_frame_talloc_ctx(request_t *request);
224
225int unlang_interpret_init_global(TALLOC_CTX *ctx);
226#ifdef __cplusplus
227}
228#endif
A section grouping multiple CONF_PAIR.
Definition cf_priv.h:101
void unlang_interpret_request_prioritise(request_t *request, uint32_t priority)
Definition interpret.c:1300
rlm_rcode_t unlang_interpret(request_t *request, bool running)
Run the interpreter for a current request.
Definition interpret.c:941
bool unlang_request_is_done(request_t const *request)
Return whether a request has been marked done.
Definition interpret.c:1586
unlang_request_prioritise_t prioritise
Function to re-priotise a request in the runnable queue.
Definition interpret.h:129
unlang_mod_action_t priority
The priority or action for that rcode.
Definition interpret.h:136
unlang_result_t * unlang_interpret_result(request_t *request)
Get the last instruction result OR the last frame that was popped.
Definition interpret.c:1561
void unlang_interpet_frame_discard(request_t *request)
Discard the bottom most frame on the request's stack.
Definition interpret.c:1986
int unlang_interpret_set_timeout(request_t *request, fr_time_delta_t timeout)
Set a timeout for a request.
Definition interpret.c:1504
void unlang_interpret_request_done(request_t *request)
Indicate to the caller of the interpreter that this request is complete.
Definition interpret.c:1255
void unlang_interpret_set(request_t *request, unlang_interpret_t *intp)
Set a specific interpreter for a request.
Definition interpret.c:1994
unlang_mod_action_t default_priority
The default priority for the frame.
Definition interpret.h:147
unlang_interpret_t * unlang_interpret_get(request_t *request)
Get the interpreter set for a request.
Definition interpret.c:2003
unlang_request_done_t done_internal
Function called when an internal request completes.
Definition interpret.h:119
int unlang_interpret_stack_depth(request_t *request)
Return the depth of the request's stack.
Definition interpret.c:1529
void unlang_interpret_mark_runnable(request_t *request)
Mark a request as resumable.
Definition interpret.c:1616
TALLOC_CTX * unlang_interpret_frame_talloc_ctx(request_t *request)
Get a talloc_ctx which is valid only for this frame.
Definition interpret.c:1661
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.
Definition interpret.c:1953
bool unlang_request_is_scheduled(request_t const *request)
Return whether a request is currently scheduled.
Definition interpret.c:1569
int unlang_interpret_init_global(TALLOC_CTX *ctx)
Definition interpret.c:2043
unlang_interpret_t * unlang_interpret_get_thread_default(void)
Get the default interpreter for this thread.
Definition interpret.c:2036
unlang_request_resume_t resume
Function called when a request is resumed.
Definition interpret.h:124
void * unlang_interpret_stack_alloc(TALLOC_CTX *ctx)
Allocate a new unlang stack.
Definition interpret.c:1194
bool top_frame
Is this the top frame?
Definition interpret.h:142
bool(* unlang_request_scheduled_t)(request_t const *request, void *uctx)
Signal the owner of the interpreter that a request is now runnable.
Definition interpret.h:90
unlang_request_done_t done_external
Function called when a external request completes.
Definition interpret.h:118
void unlang_interpret_set_thread_default(unlang_interpret_t *intp)
Set the default interpreter for this thread.
Definition interpret.c:2025
unlang_request_init_t detach
Function called when a request is detached.
Definition interpret.h:122
unlang_mod_action_t unlang_interpret_priority(request_t *request)
Get the last instruction priority OR the last frame that was popped.
Definition interpret.c:1551
unlang_request_runnable_t mark_runnable
Function called when a request needs to be added back to the runnable queue.
Definition interpret.h:125
rlm_rcode_t rcode
The current rcode, from executing the instruction or merging the result from a frame.
Definition interpret.h:134
bool unlang_request_is_cancelled(request_t const *request)
Return whether a request has been cancelled.
Definition interpret.c:1579
int unlang_interpret_push_instruction(unlang_result_t *p_result, request_t *request, void *instruction, unlang_frame_conf_t const *conf)
Push an instruction onto the request stack for later interpretation.
Definition interpret.c:1166
unlang_request_yield_t yield
Function called when a request yields.
Definition interpret.h:123
void unlang_interpret_signal(request_t *request, fr_signal_t action)
Send a signal (usually stop) to a request.
Definition interpret.c:1396
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.
Definition interpret.h:60
void(* unlang_request_prioritise_t)(request_t *request, void *uctx)
Re-priotise the request in the runnable queue.
Definition interpret.h:96
int unlang_interpret_push_section(unlang_result_t *p_result, request_t *request, CONF_SECTION *cs, unlang_frame_conf_t const *conf)
Push a configuration section onto the request stack for later interpretation.
Definition interpret.c:1143
void(* unlang_request_resume_t)(request_t *request, void *uctx)
Signal the owner of the interpreter that a request is ready to be resumed.
Definition interpret.h:78
unlang_request_done_t done_detached
Function called when a detached request completes.
Definition interpret.h:120
void(* unlang_request_yield_t)(request_t *request, void *uctx)
Signal the owner of the interpreter that a request has yielded.
Definition interpret.h:72
rlm_rcode_t default_rcode
The default return code for the frame.
Definition interpret.h:143
bool unlang_interpret_is_resumable(request_t *request)
Check if a request as resumable.
Definition interpret.c:1598
rlm_rcode_t unlang_interpret_synchronous(fr_event_list_t *el, request_t *request)
Execute an unlang section synchronously.
void(* unlang_request_init_t)(request_t *request, void *uctx)
Signal the owner of the interpreter that this request should be initialised and executed.
Definition interpret.h:54
unlang_request_scheduled_t scheduled
Function to check if a request is already scheduled.
Definition interpret.h:127
void(* unlang_request_stop_t)(request_t *request, void *uctx)
Stop a request from running.
Definition interpret.h:66
void(* unlang_request_runnable_t)(request_t *request, void *uctx)
Signal the owner of the interpreter that a request is now runnable.
Definition interpret.h:84
rlm_rcode_t unlang_interpret_rcode(request_t *request)
Get the last instruction result OR the last frame that was popped.
Definition interpret.c:1541
unlang_request_init_t init_internal
Function called to initialise an internal request.
Definition interpret.h:116
fr_event_list_t * unlang_interpret_event_list(request_t *request)
Get the event list for the current interpreter.
Definition interpret.c:2013
Configuration structure to make it easier to pass configuration options to initialise the frame with.
Definition interpret.h:141
External functions provided by the owner of the interpret.
Definition interpret.h:110
Stores all information relating to an event list.
Definition event.c:377
unsigned int uint32_t
unsigned char bool
unlang_mod_action_t
Definition mod_action.h:39
static rs_t * conf
Definition radsniff.c:53
rlm_rcode_t
Return codes indicating the result of the module call.
Definition rcode.h:40
fr_signal_t
Signals that can be generated/processed by request signal handlers.
Definition signal.h:38
A time delta, a difference in time measured in nanoseconds.
Definition time.h:80
static fr_event_list_t * el
int nonnull(2, 5))