1 /** @file
2
3 Public RecCore declarations
4
5 @section license License
6
7 Licensed to the Apache Software Foundation (ASF) under one
8 or more contributor license agreements. See the NOTICE file
9 distributed with this work for additional information
10 regarding copyright ownership. The ASF licenses this file
11 to you under the Apache License, Version 2.0 (the
12 "License"); you may not use this file except in compliance
13 with the License. You may obtain a copy of the License at
14
15 http://www.apache.org/licenses/LICENSE-2.0
16
17 Unless required by applicable law or agreed to in writing, software
18 distributed under the License is distributed on an "AS IS" BASIS,
19 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
20 See the License for the specific language governing permissions and
21 limitations under the License.
22 */
23
24 #pragma once
25
26 #include <functional>
27
28 #include "tscore/Diags.h"
29
30 #include "I_RecDefs.h"
31 #include "I_RecAlarms.h"
32 #include "I_RecSignals.h"
33 #include "I_RecEvents.h"
34 #include "tscpp/util/MemSpan.h"
35
36 struct RecRecord;
37
38 //-------------------------------------------------------------------------
39 // Diagnostic Output
40 //-------------------------------------------------------------------------
41 int RecSetDiags(Diags *diags);
42
43 //-------------------------------------------------------------------------
44 // Config File Parsing
45 //-------------------------------------------------------------------------
46 typedef void (*RecConfigEntryCallback)(RecT rec_type, RecDataT data_type, const char *name, const char *value, RecSourceT source);
47
48 void RecConfigFileInit();
49 int RecConfigFileParse(const char *path, RecConfigEntryCallback handler);
50
51 // Return a copy of the system's configuration directory.
52 std::string RecConfigReadConfigDir();
53
54 // Return a copy of the system's local state directory, taking proxy.config.local_state_dir into account.
55 std::string RecConfigReadRuntimeDir();
56
57 // Return a copy of the system's log directory, taking proxy.config.log.logfile_dir into account.
58 std::string RecConfigReadLogDir();
59
60 // Return a copy of the system's bin directory, taking proxy.config.bin_path into account.
61 std::string RecConfigReadBinDir();
62
63 // Return a copy of the system's plugin directory, taking proxy.config.plugin.plugin_dir into account.
64 std::string RecConfigReadPluginDir();
65
66 // Return a copy of a configuration file that is relative to sysconfdir. The relative path to the configuration
67 // file is specified in the configuration variable named by "file_variable". If the configuration variable has no
68 // value, nullptr is returned.
69 std::string RecConfigReadConfigPath(const char *file_variable, const char *default_value = nullptr);
70
71 // Return a copy of the persistent stats file. This is $RUNTIMEDIR/records.snap.
72 std::string RecConfigReadPersistentStatsPath();
73
74 // Test whether the named configuration value is overridden by an environment variable. Return either
75 // the overridden value, or the original value. Caller MUST NOT free the result.
76 const char *RecConfigOverrideFromEnvironment(const char *name, const char *value);
77
78 //-------------------------------------------------------------------------
79 // Stat Registration
80 //-------------------------------------------------------------------------
81 RecErrT _RecRegisterStatInt(RecT rec_type, const char *name, RecInt data_default, RecPersistT persist_type);
82 #define RecRegisterStatInt(rec_type, name, data_default, persist_type) \
83 _RecRegisterStatInt((rec_type), (name), (data_default), REC_PERSISTENCE_TYPE(persist_type))
84
85 RecErrT _RecRegisterStatFloat(RecT rec_type, const char *name, RecFloat data_default, RecPersistT persist_type);
86 #define RecRegisterStatFloat(rec_type, name, data_default, persist_type) \
87 _RecRegisterStatFloat((rec_type), (name), (data_default), REC_PERSISTENCE_TYPE(persist_type))
88
89 RecErrT _RecRegisterStatString(RecT rec_type, const char *name, RecString data_default, RecPersistT persist_type);
90 #define RecRegisterStatString(rec_type, name, data_default, persist_type) \
91 _RecRegisterStatString((rec_type), (name), (data_default), REC_PERSISTENCE_TYPE(persist_type))
92
93 RecErrT _RecRegisterStatCounter(RecT rec_type, const char *name, RecCounter data_default, RecPersistT persist_type);
94 #define RecRegisterStatCounter(rec_type, name, data_default, persist_type) \
95 _RecRegisterStatCounter((rec_type), (name), (data_default), REC_PERSISTENCE_TYPE(persist_type))
96
97 //-------------------------------------------------------------------------
98 // Config Registration
99 //-------------------------------------------------------------------------
100
101 RecErrT RecRegisterConfigInt(RecT rec_type, const char *name, RecInt data_default, RecUpdateT update_type, RecCheckT check_type,
102 const char *ccheck_regex, RecSourceT source, RecAccessT access_type = RECA_NULL);
103
104 RecErrT RecRegisterConfigFloat(RecT rec_type, const char *name, RecFloat data_default, RecUpdateT update_type, RecCheckT check_type,
105 const char *check_regex, RecSourceT source, RecAccessT access_type = RECA_NULL);
106
107 RecErrT RecRegisterConfigString(RecT rec_type, const char *name, const char *data_default, RecUpdateT update_type,
108 RecCheckT check_type, const char *check_regex, RecSourceT source,
109 RecAccessT access_type = RECA_NULL);
110
111 RecErrT RecRegisterConfigCounter(RecT rec_type, const char *name, RecCounter data_default, RecUpdateT update_type,
112 RecCheckT check_type, const char *check_regex, RecSourceT source,
113 RecAccessT access_type = RECA_NULL);
114
115 //-------------------------------------------------------------------------
116 // Config Change Notification
117 //-------------------------------------------------------------------------
118
119 RecErrT RecLinkConfigInt(const char *name, RecInt *rec_int);
120 RecErrT RecLinkConfigInt32(const char *name, int32_t *p_int32);
121 RecErrT RecLinkConfigUInt32(const char *name, uint32_t *p_uint32);
122 RecErrT RecLinkConfigFloat(const char *name, RecFloat *rec_float);
123 RecErrT RecLinkConfigCounter(const char *name, RecCounter *rec_counter);
124 RecErrT RecLinkConfigString(const char *name, RecString *rec_string);
125 RecErrT RecLinkConfigByte(const char *name, RecByte *rec_byte);
126 RecErrT RecLinkConfigBool(const char *name, RecBool *rec_byte);
127
128 RecErrT RecRegisterConfigUpdateCb(const char *name, RecConfigUpdateCb update_cb, void *cookie);
129 RecErrT RecRegisterRawStatUpdateFunc(const char *name, RecRawStatBlock *rsb, int id, RecStatUpdateFunc update_func, void *cookie);
130
131 //-------------------------------------------------------------------------
132 // Record Reading/Writing
133 //-------------------------------------------------------------------------
134
135 // WARNING! Avoid deadlocks by calling the following set/get calls
136 // with the appropriate locking conventions. If you're calling these
137 // functions from a configuration update callback (RecConfigUpdateCb),
138 // be sure to set 'lock' to 'false' as the hash-table rwlock has
139 // already been taken out for the callback.
140
141 // RecSetRecordConvert -> WebMgmtUtils.cc::varSetFromStr()
142 RecErrT RecSetRecordConvert(const char *name, const RecString rec_string, RecSourceT source, bool lock = true);
143 RecErrT RecSetRecordInt(const char *name, RecInt rec_int, RecSourceT source, bool lock = true);
144 RecErrT RecSetRecordFloat(const char *name, RecFloat rec_float, RecSourceT source, bool lock = true);
145 RecErrT RecSetRecordString(const char *name, const RecString rec_string, RecSourceT source, bool lock = true);
146 RecErrT RecSetRecordCounter(const char *name, RecCounter rec_counter, RecSourceT source, bool lock = true);
147
148 RecErrT RecGetRecordInt(const char *name, RecInt *rec_int, bool lock = true);
149 RecErrT RecGetRecordFloat(const char *name, RecFloat *rec_float, bool lock = true);
150 RecErrT RecGetRecordString(const char *name, char *buf, int buf_len, bool lock = true);
151 RecErrT RecGetRecordString_Xmalloc(const char *name, RecString *rec_string, bool lock = true);
152 RecErrT RecGetRecordCounter(const char *name, RecCounter *rec_counter, bool lock = true);
153 // Convenience to allow us to treat the RecInt as a single byte internally
154 RecErrT RecGetRecordByte(const char *name, RecByte *rec_byte, bool lock = true);
155 // Convenience to allow us to treat the RecInt as a bool internally
156 RecErrT RecGetRecordBool(const char *name, RecBool *rec_byte, bool lock = true);
157
158 //------------------------------------------------------------------------
159 // Record Attributes Reading
160 //------------------------------------------------------------------------
161 typedef void (*RecLookupCallback)(const RecRecord *, void *);
162
163 RecErrT RecLookupRecord(const char *name, RecLookupCallback callback, void *data, bool lock = true);
164 RecErrT RecLookupMatchingRecords(unsigned rec_type, const char *match, RecLookupCallback callback, void *data, bool lock = true);
165
166 RecErrT RecGetRecordType(const char *name, RecT *rec_type, bool lock = true);
167 RecErrT RecGetRecordDataType(const char *name, RecDataT *data_type, bool lock = true);
168 RecErrT RecGetRecordPersistenceType(const char *name, RecPersistT *persist_type, bool lock = true);
169 RecErrT RecGetRecordOrderAndId(const char *name, int *order, int *id, bool lock = true, bool check_sync_cb = false);
170 RecErrT RecGetRecordUpdateType(const char *name, RecUpdateT *update_type, bool lock = true);
171 RecErrT RecGetRecordCheckType(const char *name, RecCheckT *check_type, bool lock = true);
172 RecErrT RecGetRecordCheckExpr(const char *name, char **check_expr, bool lock = true);
173 RecErrT RecGetRecordDefaultDataString_Xmalloc(char *name, char **buf, bool lock = true);
174 RecErrT RecGetRecordSource(const char *name, RecSourceT *source, bool lock = true);
175
176 RecErrT RecGetRecordAccessType(const char *name, RecAccessT *secure, bool lock = true);
177 RecErrT RecSetRecordAccessType(const char *name, RecAccessT secure, bool lock = true);
178
179 //------------------------------------------------------------------------
180 // Signal and Alarms
181 //------------------------------------------------------------------------
182
183 // RecSignalManager always sends a management signal up to traffic_manager.
184 void RecSignalManager(int id, const char *, size_t);
185
186 static inline void
RecSignalManager(int id,const char * str)187 RecSignalManager(int id, const char *str)
188 {
189 RecSignalManager(id, str, strlen(str) + 1);
190 }
191
192 // Format a message, and send it to the manager and to the Warning diagnostic.
193 void RecSignalWarning(int sig, const char *fmt, ...) TS_PRINTFLIKE(2, 3);
194
195 /// Generate a warning if any configuration name/value is not registered.
196 void RecConfigWarnIfUnregistered();
197
198 //-------------------------------------------------------------------------
199 // Backwards Compatibility Items (REC_ prefix)
200 //-------------------------------------------------------------------------
201 #define REC_ReadConfigInt32(_var, _config_var_name) \
202 do { \
203 RecInt tmp = 0; \
204 RecGetRecordInt(_config_var_name, (RecInt *)&tmp); \
205 _var = (int32_t)tmp; \
206 } while (0)
207
208 #define REC_ReadConfigInteger(_var, _config_var_name) \
209 do { \
210 RecInt tmp = 0; \
211 RecGetRecordInt(_config_var_name, &tmp); \
212 _var = tmp; \
213 } while (0)
214
215 #define REC_ReadConfigFloat(_var, _config_var_name) \
216 do { \
217 RecFloat tmp = 0; \
218 RecGetRecordFloat(_config_var_name, &tmp); \
219 _var = tmp; \
220 } while (0)
221
222 #define REC_ReadConfigStringAlloc(_var, _config_var_name) RecGetRecordString_Xmalloc(_config_var_name, (RecString *)&_var)
223
224 #define REC_ReadConfigString(_var, _config_var_name, _len) RecGetRecordString(_config_var_name, _var, _len)
225
226 #define REC_RegisterConfigUpdateFunc(_config_var_name, func, flag) RecRegisterConfigUpdateCb(_config_var_name, func, flag)
227
228 #define REC_EstablishStaticConfigInteger(_var, _config_var_name) \
229 do { \
230 RecLinkConfigInt(_config_var_name, &_var); \
231 _var = (int64_t)REC_ConfigReadInteger(_config_var_name); \
232 } while (0)
233
234 #define REC_EstablishStaticConfigInt32(_var, _config_var_name) \
235 do { \
236 RecLinkConfigInt32(_config_var_name, &_var); \
237 _var = (int32_t)REC_ConfigReadInteger(_config_var_name); \
238 } while (0)
239
240 #define REC_EstablishStaticConfigInt32U(_var, _config_var_name) \
241 do { \
242 RecLinkConfigUInt32(_config_var_name, &_var); \
243 _var = (int32_t)REC_ConfigReadInteger(_config_var_name); \
244 } while (0)
245
246 /*
247 * RecLinkConfigString allocates the RecString and stores the ptr to it (&var).
248 * So before changing _var (the RecString) we have to free the original one.
249 * Really, we somehow need to know whether RecLinkConfigString allocated _var.
250 * For now, we're using the return value to indicate this, even though it's
251 * not always the case. If we're wrong, we'll leak the RecString.
252 */
253 #define REC_EstablishStaticConfigStringAlloc(_var, _config_var_name) \
254 do { \
255 if (RecLinkConfigString(_config_var_name, &_var) == REC_ERR_OKAY) \
256 ats_free(_var); \
257 _var = (RecString)REC_ConfigReadString(_config_var_name); \
258 } while (0)
259
260 #define REC_EstablishStaticConfigFloat(_var, _config_var_name) \
261 do { \
262 RecLinkConfigFloat(_config_var_name, &_var); \
263 _var = (RecFloat)REC_ConfigReadFloat(_config_var_name); \
264 } while (0)
265
266 // Allow to treat our "INT" configs as a byte type internally. Note
267 // that the byte type is just a wrapper around RECD_INT.
268 #define REC_EstablishStaticConfigByte(_var, _config_var_name) \
269 do { \
270 RecLinkConfigByte(_config_var_name, &_var); \
271 _var = (RecByte)REC_ConfigReadInteger(_config_var_name); \
272 } while (0)
273
274 // Allow to treat our "INT" configs as a bool type internally. Note
275 // that the bool type is just a wrapper around RECD_INT.
276 #define REC_EstablishStaticConfigBool(_var, _config_var_name) \
277 do { \
278 RecLinkConfigBool(_config_var_name, &_var); \
279 _var = 0 != REC_ConfigReadInteger(_config_var_name); \
280 } while (0)
281
282 RecInt REC_ConfigReadInteger(const char *name);
283 char *REC_ConfigReadString(const char *name);
284 RecFloat REC_ConfigReadFloat(const char *name);
285 RecCounter REC_ConfigReadCounter(const char *name);
286
287 // MGMT2 Marco's -- converting lmgmt->record_data->readXXX
288 RecInt REC_readInteger(const char *name, bool *found, bool lock = true);
289 RecFloat REC_readFloat(char *name, bool *found, bool lock = true);
290 RecCounter REC_readCounter(char *name, bool *found, bool lock = true);
291 RecString REC_readString(const char *name, bool *found, bool lock = true);
292
293 //------------------------------------------------------------------------
294 // Clear Statistics
295 //------------------------------------------------------------------------
296 RecErrT RecResetStatRecord(const char *name);
297 RecErrT RecResetStatRecord(RecT type = RECT_NULL, bool all = false);
298
299 //------------------------------------------------------------------------
300 // Set RecRecord attributes
301 //------------------------------------------------------------------------
302 RecErrT RecSetSyncRequired(char *name, bool lock = true);
303
304 //------------------------------------------------------------------------
305 // Manager Callback
306 //------------------------------------------------------------------------
307 using RecManagerCb = std::function<void(ts::MemSpan<void>)>;
308 int RecRegisterManagerCb(int _signal, RecManagerCb const &_fn);
309