2 * Copyright (C) 1996-2015 The Squid Software Foundation and contributors
4 * Squid software is distributed under GPLv2+ license and includes
5 * contributions from numerous individuals and organizations.
6 * Please see the COPYING and CONTRIBUTORS files for details.
9 #ifndef SQUID_SRC_CBDATA_H
10 #define SQUID_SRC_CBDATA_H
15 \page CBDATA Callback Data Allocator API
20 Squid's extensive use of callback functions makes it very
21 susceptible to memory access errors. To address this all callback
22 functions make use of a construct called cbdata. This allows
23 functions doing callbacks to verify that the caller is still
24 valid before making the callback.
26 \note cbdata is intended for callback data and is tailored specifically
27 to make callbacks less dangerous leaving as few windows of errors as
28 possible. It is not suitable or intended as a generic RefCount
32 The AsyncJob/AsyncCall mechanism is preferred over CBDATA.
33 It replaces cbdata with an AsyncCall::Pointer object which
34 performs the same memory protection duties via other means.
36 \section Examples Examples
38 Here you can find some examples on how to use cbdata, and why.
40 \subsection AsyncOpWithoutCBDATA Asynchronous operation without cbdata, showing why cbdata is needed
42 For a asyncronous operation with callback functions, the normal
43 sequence of events in programs NOT using cbdata is as follows:
47 type_of_data our_data = new ...;
49 // Initiate a asyncronous operation, with our_data as callback_data
50 fooOperationStart(bar, callback_func, our_data);
52 // The asyncronous operation completes and makes the callback
53 callback_func(callback_data, ....);
54 // Some time later we clean up our data
59 However, things become more interesting if we want or need
60 to free the callback_data, or otherwise cancel the callback,
61 before the operation completes. In constructs like this you
62 can quite easily end up with having the memory referenced
63 pointed to by callback_data freed before the callback is invoked
64 causing a program failure or memory corruption:
68 type_of_data our_data = new ...;
70 // Initiate a asyncronous operation, with our_data as callback_data
71 fooOperationStart(bar, callback_func, our_data);
73 // ouch, something bad happened elsewhere.. try to cleanup
74 // but the programmer forgot there is a callback pending from
75 // fooOperationsStart(). An easy thing to forget when writing code
76 // to deal with errors, especially if there may be many different
77 // pending operations.
80 // The asyncronous operation completes and makes the callback
81 callback_func(callback_data, ....);
82 // CRASH, the memory pointer to by callback_data is no longer valid
83 // at the time of the callback
86 \subsection AsyncOpWithCBDATA Asyncronous operation with cbdata
89 The callback data allocator lets us do this in a uniform and
90 safe manner. The callback data allocator is used to allocate,
91 track and free memory pool objects used during callback
92 operations. Allocated memory is locked while the asyncronous
93 operation executes elsewhere, and is freed when the operation
94 completes. The normal sequence of events is:
98 type_of_data our_data = new type_of_data;
100 // Initiate a asyncronous operation, with our_data as callback_data
101 fooOperationStart(..., callback_func, our_data);
104 void *local_pointer = cbdataReference(callback_data);
106 // The asyncronous operation completes and makes the callback
108 if (cbdataReferenceValidDone(local_pointer, &cbdata))
109 callback_func(...., cbdata);
113 \subsection AsynchronousOpCancelledByCBDATA Asynchronous operation cancelled by cbdata
116 With this scheme, nothing bad happens if delete gets called
117 before fooOperantionComplete(...).
122 type_of_data our_data = new type_of_data;
124 // Initiate a asyncronous operation, with our_data as callback_data
125 fooOperationStart(..., callback_func, our_data);
127 // do some stuff with it
128 void *local_pointer = cbdataReference(callback_data);
130 // something bad happened elsewhere.. cleanup
133 // The asyncronous operation completes and makes the callback
135 if (cbdataReferenceValidDone(local_pointer, &cbdata))
136 // won't be called, as the data is no longer valid
137 callback_func(...., cbdata);
142 In this case, when delete is called before cbdataReferenceValidDone(),
143 the callback_data gets marked as invalid.
144 When the callback_data is invalid before executing the callback
145 function, cbdataReferenceValidDone() will return 0 and
146 callback_func is never executed.
148 \subsection AddingCBDATAType Adding a new cbdata registered type
151 To add new module specific data types to the allocator one uses
152 the macro CBDATA_CLASS() in the class private section, and
153 CBDATA_CLASS_INIT() or CBDATA_NAMESPACED_CLASS_INIT() in the
166 CBDATA_CLASS_INIT(Foo);
170 These macros create new(), delete() and toCbdata() methods
171 definition in class scope. Any allocate calls must be made with
172 new() and destruction with delete(), they may be called from
176 The class constructor must make sure that all member
177 variables are initialized, and the class destructor that all
178 dynamic memory is released.
181 The CbcPointer<> template should be used to create a smart-pointer
182 type for simple reference tracking. It provides get() and valid()
183 accessors for use instead of cbdataReferenceValid(), and performs
184 reliable automatic cbdataReference() and cbdataReferenceDone()
186 Note that it does NOT provide a replacement for cbdataReferenceValidDone().
191 * cbdata types. Similar to the MEM_* types, but managed in cbdata.cc
192 * A big difference is that cbdata types are dynamically allocated.
194 * Initially only UNKNOWN type is predefined.
195 * Other types are added at runtime by CBDATA_CLASS().
197 typedef int cbdata_type
;
198 static const cbdata_type CBDATA_UNKNOWN
= 0;
201 * Create a run-time registration of CBDATA component with
204 void cbdataRegisterWithCacheManager(void);
207 * Allocates a new entry of a registered CBDATA type.
209 * \note For internal CBDATA use only.
211 void *cbdataInternalAlloc(cbdata_type type
, const char *, int);
214 * Frees a entry allocated by cbdataInternalAlloc().
216 * Once this has been called cbdataReferenceValid() and
217 * cbdataReferenceValidDone() will return false regardless
218 * of whether there are remaining cbdata references.
220 * cbdataReferenceDone() must still be called for any active
221 * references to the cbdata entry. The cbdata entry will be freed
222 * only when the last reference is removed.
224 * \note For internal CBDATA use only.
226 void *cbdataInternalFree(void *p
, const char *, int);
229 void cbdataInternalLockDbg(const void *p
, const char *, int);
230 #define cbdataInternalLock(a) cbdataInternalLockDbg(a,__FILE__,__LINE__)
232 void cbdataInternalUnlockDbg(const void *p
, const char *, int);
233 #define cbdataInternalUnlock(a) cbdataInternalUnlockDbg(a,__FILE__,__LINE__)
235 int cbdataInternalReferenceDoneValidDbg(void **p
, void **tp
, const char *, int);
236 #define cbdataReferenceValidDone(var, ptr) cbdataInternalReferenceDoneValidDbg((void **)&(var), (ptr), __FILE__,__LINE__)
239 void cbdataInternalLock(const void *p
);
240 void cbdataInternalUnlock(const void *p
);
243 * Removes a reference created by cbdataReference() and checks
244 * it for validity. Meant to be used on the last dereference,
245 * usually to make a callback.
250 if (cbdataReferenceValidDone(reference, &cbdata)) != NULL)
251 callback(..., cbdata);
254 * \param var The reference variable. Will be automatically cleared to NULL.
255 * \param ptr A temporary pointer to the referenced data (if valid).
257 int cbdataInternalReferenceDoneValid(void **p
, void **tp
);
258 #define cbdataReferenceValidDone(var, ptr) cbdataInternalReferenceDoneValid((void **)&(var), (ptr))
260 #endif /* !CBDATA_DEBUG */
263 * \param p A cbdata entry reference pointer.
265 * \retval 0 A reference is stale. The pointer refers to a entry already freed.
266 * \retval true The reference is valid and active.
268 int cbdataReferenceValid(const void *p
);
271 * Create a run-time registration for the class type with cbdata memory allocator.
273 * \note For internal CBDATA use only.
275 cbdata_type
cbdataInternalAddType(cbdata_type type
, const char *label
, int size
, FREE
* free_func
);
278 * This needs to be defined FIRST in the class definition.
279 * It plays with private/public states in C++.
281 #define CBDATA_CLASS(type) \
283 void *operator new(size_t size) { \
284 assert(size == sizeof(type)); \
285 if (!CBDATA_##type) CBDATA_##type = cbdataInternalAddType(CBDATA_##type, #type, sizeof(type), NULL); \
286 return (type *)cbdataInternalAlloc(CBDATA_##type,__FILE__,__LINE__); \
288 void operator delete (void *address) { \
289 if (address) cbdataInternalFree(address,__FILE__,__LINE__); \
291 void *toCbdata() { return this; } \
293 static cbdata_type CBDATA_##type;
296 * Creates a global instance pointer for the CBDATA memory allocator
297 * to allocate and free objects for the matching CBDATA_CLASS().
299 * Place this in the appropriate .cc file for the class being registered.
301 * May be placed inside an explicit namespace scope declaration,
302 * or CBDATA_NAMESPACED_CLASS_INIT() used instead.
304 #define CBDATA_CLASS_INIT(type) cbdata_type type::CBDATA_##type = CBDATA_UNKNOWN
307 * Creates a global instance pointer for the CBDATA memory allocator
308 * to allocate and free objects for the matching CBDATA_CLASS().
310 * Place this in the appropriate .cc file for the class being registered.
312 #define CBDATA_NAMESPACED_CLASS_INIT(namespace, type) cbdata_type namespace::type::CBDATA_##type = CBDATA_UNKNOWN
315 * Creates a new reference to a cbdata entry. Used when you need to
316 * store a reference in another structure. The reference can later
317 * be verified for validity by cbdataReferenceValid().
319 * \deprecated Prefer the use of CbcPointer<> smart pointer.
322 * The reference variable is a pointer to the entry, in all
323 * aspects identical to the original pointer. But semantically it
324 * is quite different. It is best if the reference is thought of
325 * and handled as a "void *".
327 #define cbdataReference(var) (cbdataInternalLock(var), var)
330 * Removes a reference created by cbdataReference().
332 * \deprecated Prefer the use of CbcPointer<> smart pointer.
334 * \param var The reference variable. Will be automatically cleared to NULL.
336 #define cbdataReferenceDone(var) do {if (var) {cbdataInternalUnlock(var); var = NULL;}} while(0)
339 * A generic wrapper for passing object pointers through cbdata.
340 * Use this when you need to pass callback data to a blocking
341 * operation, but you don't want to/cannot have that pointer be
346 CBDATA_CLASS(generic_cbdata
);
349 generic_cbdata(void *aData
) : data(aData
) {}
351 template<typename wrapped_type
>void unwrap(wrapped_type
**output
) {
352 *output
= static_cast<wrapped_type
*>(data
);
360 #endif /* SQUID_CBDATA_H */