The FreeRADIUS server  $Id: 15bac2a4c627c01d1aa2047687b3418955ac7f00 $
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: 12740dbb4569642bbea08daf30584919a72b31ce $
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
28 extern "C" {
29 #endif
30 
31 #include <freeradius-devel/server/cf_util.h>
32 #include <freeradius-devel/server/request.h>
33 #include <freeradius-devel/unlang/action.h>
34 
35 #define UNLANG_TOP_FRAME (true)
36 #define UNLANG_SUB_FRAME (false)
37 
38 #define UNLANG_STACK_MAX (64) //!< The maximum depth of the stack.
39 #define UNLANG_FRAME_PRE_ALLOC (128) //!< How much memory we pre-alloc for each frame.
40 
41 /** Interpreter handle
42  *
43  */
45 
46 /** Signal the owner of the interpreter that this request should be initialised and executed
47  *
48  * This is called once per request, when it's about to start executing.
49  */
50 typedef void (*unlang_request_init_t)(request_t *request, void *uctx);
51 
52 /** Signal the owner of the interpreter that this request completed processing
53  *
54  * This is called once per request, when the interpret is about to stop processing it.
55  */
56 typedef void (*unlang_request_done_t)(request_t *request, rlm_rcode_t rcode, void *uctx);
57 
58 /** Stop a request from running
59  *
60  * This is called whenever a request has been signalled to stop
61  */
62 typedef void (*unlang_request_stop_t)(request_t *request, void *uctx);
63 
64 /** Signal the owner of the interpreter that a request has yielded
65  *
66  * This is called whenever a request has given control back to the interpreter.
67  */
68 typedef void (*unlang_request_yield_t)(request_t *request, void *uctx);
69 
70 /** Signal the owner of the interpreter that a request is ready to be resumed
71  *
72  * This is called any time a yielded request has resumed.
73  */
74 typedef void (*unlang_request_resume_t)(request_t *request, void *uctx);
75 
76 /** Signal the owner of the interpreter that a request is now runnable
77  *
78  * This is called any time a yielded request has been marked runnable.
79  */
80 typedef void (*unlang_request_runnable_t)(request_t *request, void *uctx);
81 
82 /** Signal the owner of the interpreter that a request is now runnable
83  *
84  * This is called any time a yielded request has been marked runnable.
85  */
86 typedef bool (*unlang_request_scheduled_t)(request_t const *request, void *uctx);
87 
88 /** External functions provided by the owner of the interpret
89  *
90  * These functions allow the event loop to signal the caller when a given
91  * request is ready to run for the first time, and when it should be resumed
92  * and passed back to #unlang_interpret to continue execution.
93  *
94  * This is the cleanest way to separate the interpret and the code that's
95  * managing requests.
96  *
97  * Test harnesses (for example) need to perform far less initialisation and
98  * request management than FeeRADIUS worker threads.
99  */
100 typedef struct {
101  /*
102  * There's no init_external as this is done
103  * before the external request is handed off
104  * to the interpreter.
105  */
106  unlang_request_init_t init_internal; //!< Function called to initialise an internal request.
107 
108  unlang_request_done_t done_external; //!< Function called when a external request completes.
109  unlang_request_done_t done_internal; //!< Function called when an internal request completes.
110  unlang_request_done_t done_detached; //!< Function called when a detached request completes.
111 
112  unlang_request_init_t detach; //!< Function called when a request is detached.
113  unlang_request_stop_t stop; //!< function called when a request is signalled to stop.
114  unlang_request_yield_t yield; //!< Function called when a request yields.
115  unlang_request_resume_t resume; //!< Function called when a request is resumed.
116  unlang_request_runnable_t mark_runnable; //!< Function called when a request needs to be
117  ///< added back to the runnable queue.
118  unlang_request_scheduled_t scheduled; //!< Function to check if a request is already
119  ///< scheduled.
121 
123  rlm_rcode_t default_action, bool top_frame)
124  CC_HINT(warn_unused_result);
125 
126 int unlang_interpret_push_instruction(request_t *request, void *instruction,
127  rlm_rcode_t default_rcode, bool top_frame)
128  CC_HINT(warn_unused_result);
129 
132 
134 
136 
138 
140 
142 
144 
145 rlm_rcode_t unlang_interpret(request_t *request) CC_HINT(hot);
146 
148 
149 void *unlang_interpret_stack_alloc(TALLOC_CTX *ctx);
150 
151 bool unlang_request_is_scheduled(request_t const *request);
152 
153 bool unlang_request_is_cancelled(request_t const *request);
154 
155 bool unlang_request_is_done(request_t const *request);
156 
158 
160 
162 
163 void unlang_interpret_signal(request_t *request, fr_signal_t action);
164 
166 
168 
170 
171 TALLOC_CTX *unlang_interpret_frame_talloc_ctx(request_t *request);
172 
173 int unlang_interpret_init_global(TALLOC_CTX *ctx);
174 #ifdef __cplusplus
175 }
176 #endif
A section grouping multiple CONF_PAIR.
Definition: cf_priv.h:101
fr_dcursor_eval_t void const * uctx
Definition: dcursor.h:546
unlang_request_stop_t stop
function called when a request is signalled to stop.
Definition: interpret.h:113
rlm_rcode_t unlang_interpret(request_t *request)
Run the interpreter for a current request.
Definition: interpret.c:770
fr_event_list_t * unlang_interpret_event_list(request_t *request)
Get the event list for the current interpreter.
Definition: interpret.c:1764
bool unlang_request_is_done(request_t const *request)
Return whether a request has been marked done.
Definition: interpret.c:1329
void unlang_interpet_frame_discard(request_t *request)
Discard the bottom most frame on the request's stack.
Definition: interpret.c:1737
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: interpret.c:1015
void unlang_interpret_request_done(request_t *request)
Indicate to the caller of the interpreter that this request is complete.
Definition: interpret.c:1072
unlang_interpret_t * unlang_interpret_get(request_t *request)
Get the interpreter set for a request.
Definition: interpret.c:1754
void unlang_interpret_set(request_t *request, unlang_interpret_t *intp)
Set a specific interpreter for a request.
Definition: interpret.c:1745
rlm_rcode_t unlang_interpret_stack_result(request_t *request)
Get the current rcode for the frame.
Definition: interpret.c:1290
unlang_request_done_t done_internal
Function called when an internal request completes.
Definition: interpret.h:109
int unlang_interpret_stack_depth(request_t *request)
Return the depth of the request's stack.
Definition: interpret.c:1275
void unlang_interpret_mark_runnable(request_t *request)
Mark a request as resumable.
Definition: interpret.c:1359
bool unlang_request_is_scheduled(request_t const *request)
Return whether a request is currently scheduled.
Definition: interpret.c:1312
int unlang_interpret_init_global(TALLOC_CTX *ctx)
Definition: interpret.c:1794
unlang_request_resume_t resume
Function called when a request is resumed.
Definition: interpret.h:115
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:86
unlang_request_done_t done_external
Function called when a external request completes.
Definition: interpret.h:108
void unlang_interpret_set_thread_default(unlang_interpret_t *intp)
Set the default interpreter for this thread.
Definition: interpret.c:1776
unlang_request_init_t detach
Function called when a request is detached.
Definition: interpret.h:112
unlang_request_runnable_t mark_runnable
Function called when a request needs to be added back to the runnable queue.
Definition: interpret.h:116
bool unlang_request_is_cancelled(request_t const *request)
Return whether a request has been cancelled.
Definition: interpret.c:1322
unlang_request_yield_t yield
Function called when a request yields.
Definition: interpret.h:114
void unlang_interpret_signal(request_t *request, fr_signal_t action)
Send a signal (usually stop) to a request.
Definition: interpret.c:1196
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:56
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:74
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:1703
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: interpret.c:992
unlang_request_done_t done_detached
Function called when a detached request completes.
Definition: interpret.h:110
void(* unlang_request_yield_t)(request_t *request, void *uctx)
Signal the owner of the interpreter that a request has yielded.
Definition: interpret.h:68
bool unlang_interpret_is_resumable(request_t *request)
Check if a request as resumable.
Definition: interpret.c:1341
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:50
void unlang_interpret_stack_result_set(request_t *request, rlm_rcode_t code)
Overwrite the current stack rcode.
Definition: interpret.c:1302
TALLOC_CTX * unlang_interpret_frame_talloc_ctx(request_t *request)
Get a talloc_ctx which is valid only for this frame.
Definition: interpret.c:1403
unlang_request_scheduled_t scheduled
Function to check if a request is already scheduled.
Definition: interpret.h:118
void(* unlang_request_stop_t)(request_t *request, void *uctx)
Stop a request from running.
Definition: interpret.h:62
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:80
void * unlang_interpret_stack_alloc(TALLOC_CTX *ctx)
Allocate a new unlang stack.
Definition: interpret.c:1046
unlang_request_init_t init_internal
Function called to initialise an internal request.
Definition: interpret.h:106
unlang_interpret_t * unlang_interpret_get_thread_default(void)
Get the default interpreter for this thread.
Definition: interpret.c:1787
External functions provided by the owner of the interpret.
Definition: interpret.h:100
Stores all information relating to an event list.
Definition: event.c:411
unsigned char bool
Definition: merged_model.c:19
rlm_rcode_t
Return codes indicating the result of the module call.
Definition: rcode.h:40
fr_signal_t
Definition: signal.h:48
static fr_event_list_t * el