| OLD | NEW |
|---|
| (Empty) |
| 1 Using talloc in Samba4 | |
| 2 ====================== | |
| 3 | |
| 4 .. contents:: | |
| 5 | |
| 6 Andrew Tridgell | |
| 7 August 2009 | |
| 8 | |
| 9 The most current version of this document is available at | |
| 10 http://samba.org/ftp/unpacked/talloc/talloc_guide.txt | |
| 11 | |
| 12 If you are used to the "old" talloc from Samba3 before 3.0.20 then please read | |
| 13 this carefully, as talloc has changed a lot. With 3.0.20 (or 3.0.14?) the | |
| 14 Samba4 talloc has been ported back to Samba3, so this guide applies to both. | |
| 15 | |
| 16 The new talloc is a hierarchical, reference counted memory pool system | |
| 17 with destructors. Quite a mouthful really, but not too bad once you | |
| 18 get used to it. | |
| 19 | |
| 20 Perhaps the biggest change from Samba3 is that there is no distinction | |
| 21 between a "talloc context" and a "talloc pointer". Any pointer | |
| 22 returned from talloc() is itself a valid talloc context. This means | |
| 23 you can do this:: | |
| 24 | |
| 25 struct foo *X = talloc(mem_ctx, struct foo); | |
| 26 X->name = talloc_strdup(X, "foo"); | |
| 27 | |
| 28 and the pointer X->name would be a "child" of the talloc context "X" | |
| 29 which is itself a child of mem_ctx. So if you do talloc_free(mem_ctx) | |
| 30 then it is all destroyed, whereas if you do talloc_free(X) then just X | |
| 31 and X->name are destroyed, and if you do talloc_free(X->name) then | |
| 32 just the name element of X is destroyed. | |
| 33 | |
| 34 If you think about this, then what this effectively gives you is an | |
| 35 n-ary tree, where you can free any part of the tree with | |
| 36 talloc_free(). | |
| 37 | |
| 38 If you find this confusing, then I suggest you run the testsuite to | |
| 39 watch talloc in action. You may also like to add your own tests to | |
| 40 testsuite.c to clarify how some particular situation is handled. | |
| 41 | |
| 42 | |
| 43 Performance | |
| 44 ----------- | |
| 45 | |
| 46 All the additional features of talloc() over malloc() do come at a | |
| 47 price. We have a simple performance test in Samba4 that measures | |
| 48 talloc() versus malloc() performance, and it seems that talloc() is | |
| 49 about 4% slower than malloc() on my x86 Debian Linux box. For Samba, | |
| 50 the great reduction in code complexity that we get by using talloc | |
| 51 makes this worthwhile, especially as the total overhead of | |
| 52 talloc/malloc in Samba is already quite small. | |
| 53 | |
| 54 | |
| 55 talloc API | |
| 56 ---------- | |
| 57 | |
| 58 The following is a complete guide to the talloc API. Read it all at | |
| 59 least twice. | |
| 60 | |
| 61 Multi-threading | |
| 62 --------------- | |
| 63 | |
| 64 talloc itself does not deal with threads. It is thread-safe (assuming | |
| 65 the underlying "malloc" is), as long as each thread uses different | |
| 66 memory contexts. | |
| 67 If two threads uses the same context then they need to synchronize in | |
| 68 order to be safe. In particular: | |
| 69 - when using talloc_enable_leak_report(), giving directly NULL as a | |
| 70 parent context implicitly refers to a hidden "null context" global | |
| 71 variable, so this should not be used in a multi-threaded environment | |
| 72 without proper synchronization ; | |
| 73 - the context returned by talloc_autofree_context() is also global so | |
| 74 shouldn't be used by several threads simultaneously without | |
| 75 synchronization. | |
| 76 | |
| 77 | |
| 78 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 79 (type *)talloc(const void *context, type); | |
| 80 | |
| 81 The talloc() macro is the core of the talloc library. It takes a | |
| 82 memory context and a type, and returns a pointer to a new area of | |
| 83 memory of the given type. | |
| 84 | |
| 85 The returned pointer is itself a talloc context, so you can use it as | |
| 86 the context argument to more calls to talloc if you wish. | |
| 87 | |
| 88 The returned pointer is a "child" of the supplied context. This means | |
| 89 that if you talloc_free() the context then the new child disappears as | |
| 90 well. Alternatively you can free just the child. | |
| 91 | |
| 92 The context argument to talloc() can be NULL, in which case a new top | |
| 93 level context is created. | |
| 94 | |
| 95 | |
| 96 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 97 void *talloc_size(const void *context, size_t size); | |
| 98 | |
| 99 The function talloc_size() should be used when you don't have a | |
| 100 convenient type to pass to talloc(). Unlike talloc(), it is not type | |
| 101 safe (as it returns a void *), so you are on your own for type checking. | |
| 102 | |
| 103 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 104 (typeof(ptr)) talloc_ptrtype(const void *ctx, ptr); | |
| 105 | |
| 106 The talloc_ptrtype() macro should be used when you have a pointer and | |
| 107 want to allocate memory to point at with this pointer. When compiling | |
| 108 with gcc >= 3 it is typesafe. Note this is a wrapper of talloc_size() | |
| 109 and talloc_get_name() will return the current location in the source file. | |
| 110 and not the type. | |
| 111 | |
| 112 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 113 int talloc_free(void *ptr); | |
| 114 | |
| 115 The talloc_free() function frees a piece of talloc memory, and all its | |
| 116 children. You can call talloc_free() on any pointer returned by | |
| 117 talloc(). | |
| 118 | |
| 119 The return value of talloc_free() indicates success or failure, with 0 | |
| 120 returned for success and -1 for failure. The only possible failure | |
| 121 condition is if the pointer had a destructor attached to it and the | |
| 122 destructor returned -1. See talloc_set_destructor() for details on | |
| 123 destructors. | |
| 124 | |
| 125 If this pointer has an additional parent when talloc_free() is called | |
| 126 then the memory is not actually released, but instead the most | |
| 127 recently established parent is destroyed. See talloc_reference() for | |
| 128 details on establishing additional parents. | |
| 129 | |
| 130 For more control on which parent is removed, see talloc_unlink() | |
| 131 | |
| 132 talloc_free() operates recursively on its children. | |
| 133 | |
| 134 From the 2.0 version of talloc, as a special case, talloc_free() is | |
| 135 refused on pointers that have more than one parent, as talloc would | |
| 136 have no way of knowing which parent should be removed. To free a | |
| 137 pointer that has more than one parent please use talloc_unlink(). | |
| 138 | |
| 139 To help you find problems in your code caused by this behaviour, if | |
| 140 you do try and free a pointer with more than one parent then the | |
| 141 talloc logging function will be called to give output like this: | |
| 142 | |
| 143 ERROR: talloc_free with references at some_dir/source/foo.c:123 | |
| 144 reference at some_dir/source/other.c:325 | |
| 145 reference at some_dir/source/third.c:121 | |
| 146 | |
| 147 Please see the documentation for talloc_set_log_fn() and | |
| 148 talloc_set_log_stderr() for more information on talloc logging | |
| 149 functions. | |
| 150 | |
| 151 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 152 int talloc_free_children(void *ptr); | |
| 153 | |
| 154 The talloc_free_children() walks along the list of all children of a | |
| 155 talloc context and talloc_free()s only the children, not the context | |
| 156 itself. | |
| 157 | |
| 158 | |
| 159 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 160 void *talloc_reference(const void *context, const void *ptr); | |
| 161 | |
| 162 The talloc_reference() function makes "context" an additional parent | |
| 163 of "ptr". | |
| 164 | |
| 165 The return value of talloc_reference() is always the original pointer | |
| 166 "ptr", unless talloc ran out of memory in creating the reference in | |
| 167 which case it will return NULL (each additional reference consumes | |
| 168 around 48 bytes of memory on intel x86 platforms). | |
| 169 | |
| 170 If "ptr" is NULL, then the function is a no-op, and simply returns NULL. | |
| 171 | |
| 172 After creating a reference you can free it in one of the following | |
| 173 ways: | |
| 174 | |
| 175 - you can talloc_free() any parent of the original pointer. That | |
| 176 will reduce the number of parents of this pointer by 1, and will | |
| 177 cause this pointer to be freed if it runs out of parents. | |
| 178 | |
| 179 - you can talloc_free() the pointer itself. That will destroy the | |
| 180 most recently established parent to the pointer and leave the | |
| 181 pointer as a child of its current parent. | |
| 182 | |
| 183 For more control on which parent to remove, see talloc_unlink() | |
| 184 | |
| 185 | |
| 186 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 187 int talloc_unlink(const void *context, const void *ptr); | |
| 188 | |
| 189 The talloc_unlink() function removes a specific parent from ptr. The | |
| 190 context passed must either be a context used in talloc_reference() | |
| 191 with this pointer, or must be a direct parent of ptr. | |
| 192 | |
| 193 Note that if the parent has already been removed using talloc_free() | |
| 194 then this function will fail and will return -1. Likewise, if "ptr" | |
| 195 is NULL, then the function will make no modifications and return -1. | |
| 196 | |
| 197 Usually you can just use talloc_free() instead of talloc_unlink(), but | |
| 198 sometimes it is useful to have the additional control on which parent | |
| 199 is removed. | |
| 200 | |
| 201 | |
| 202 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 203 void talloc_set_destructor(const void *ptr, int (*destructor)(void *)); | |
| 204 | |
| 205 The function talloc_set_destructor() sets the "destructor" for the | |
| 206 pointer "ptr". A destructor is a function that is called when the | |
| 207 memory used by a pointer is about to be released. The destructor | |
| 208 receives the pointer as an argument, and should return 0 for success | |
| 209 and -1 for failure. | |
| 210 | |
| 211 The destructor can do anything it wants to, including freeing other | |
| 212 pieces of memory. A common use for destructors is to clean up | |
| 213 operating system resources (such as open file descriptors) contained | |
| 214 in the structure the destructor is placed on. | |
| 215 | |
| 216 You can only place one destructor on a pointer. If you need more than | |
| 217 one destructor then you can create a zero-length child of the pointer | |
| 218 and place an additional destructor on that. | |
| 219 | |
| 220 To remove a destructor call talloc_set_destructor() with NULL for the | |
| 221 destructor. | |
| 222 | |
| 223 If your destructor attempts to talloc_free() the pointer that it is | |
| 224 the destructor for then talloc_free() will return -1 and the free will | |
| 225 be ignored. This would be a pointless operation anyway, as the | |
| 226 destructor is only called when the memory is just about to go away. | |
| 227 | |
| 228 | |
| 229 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 230 int talloc_increase_ref_count(const void *ptr); | |
| 231 | |
| 232 The talloc_increase_ref_count(ptr) function is exactly equivalent to: | |
| 233 | |
| 234 talloc_reference(NULL, ptr); | |
| 235 | |
| 236 You can use either syntax, depending on which you think is clearer in | |
| 237 your code. | |
| 238 | |
| 239 It returns 0 on success and -1 on failure. | |
| 240 | |
| 241 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 242 size_t talloc_reference_count(const void *ptr); | |
| 243 | |
| 244 Return the number of references to the pointer. | |
| 245 | |
| 246 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 247 void talloc_set_name(const void *ptr, const char *fmt, ...); | |
| 248 | |
| 249 Each talloc pointer has a "name". The name is used principally for | |
| 250 debugging purposes, although it is also possible to set and get the | |
| 251 name on a pointer in as a way of "marking" pointers in your code. | |
| 252 | |
| 253 The main use for names on pointer is for "talloc reports". See | |
| 254 talloc_report() and talloc_report_full() for details. Also see | |
| 255 talloc_enable_leak_report() and talloc_enable_leak_report_full(). | |
| 256 | |
| 257 The talloc_set_name() function allocates memory as a child of the | |
| 258 pointer. It is logically equivalent to: | |
| 259 talloc_set_name_const(ptr, talloc_asprintf(ptr, fmt, ...)); | |
| 260 | |
| 261 Note that multiple calls to talloc_set_name() will allocate more | |
| 262 memory without releasing the name. All of the memory is released when | |
| 263 the ptr is freed using talloc_free(). | |
| 264 | |
| 265 | |
| 266 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 267 void talloc_set_name_const(const void *ptr, const char *name); | |
| 268 | |
| 269 The function talloc_set_name_const() is just like talloc_set_name(), | |
| 270 but it takes a string constant, and is much faster. It is extensively | |
| 271 used by the "auto naming" macros, such as talloc_p(). | |
| 272 | |
| 273 This function does not allocate any memory. It just copies the | |
| 274 supplied pointer into the internal representation of the talloc | |
| 275 ptr. This means you must not pass a name pointer to memory that will | |
| 276 disappear before the ptr is freed with talloc_free(). | |
| 277 | |
| 278 | |
| 279 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 280 void *talloc_named(const void *context, size_t size, const char *fmt, ...); | |
| 281 | |
| 282 The talloc_named() function creates a named talloc pointer. It is | |
| 283 equivalent to: | |
| 284 | |
| 285 ptr = talloc_size(context, size); | |
| 286 talloc_set_name(ptr, fmt, ....); | |
| 287 | |
| 288 | |
| 289 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 290 void *talloc_named_const(const void *context, size_t size, const char *name); | |
| 291 | |
| 292 This is equivalent to:: | |
| 293 | |
| 294 ptr = talloc_size(context, size); | |
| 295 talloc_set_name_const(ptr, name); | |
| 296 | |
| 297 | |
| 298 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 299 const char *talloc_get_name(const void *ptr); | |
| 300 | |
| 301 This returns the current name for the given talloc pointer. See | |
| 302 talloc_set_name() for details. | |
| 303 | |
| 304 | |
| 305 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 306 void *talloc_init(const char *fmt, ...); | |
| 307 | |
| 308 This function creates a zero length named talloc context as a top | |
| 309 level context. It is equivalent to:: | |
| 310 | |
| 311 talloc_named(NULL, 0, fmt, ...); | |
| 312 | |
| 313 | |
| 314 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 315 void *talloc_new(void *ctx); | |
| 316 | |
| 317 This is a utility macro that creates a new memory context hanging | |
| 318 off an exiting context, automatically naming it "talloc_new: __location__" | |
| 319 where __location__ is the source line it is called from. It is | |
| 320 particularly useful for creating a new temporary working context. | |
| 321 | |
| 322 | |
| 323 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 324 (type *)talloc_realloc(const void *context, void *ptr, type, count); | |
| 325 | |
| 326 The talloc_realloc() macro changes the size of a talloc | |
| 327 pointer. The "count" argument is the number of elements of type "type" | |
| 328 that you want the resulting pointer to hold. | |
| 329 | |
| 330 talloc_realloc() has the following equivalences:: | |
| 331 | |
| 332 talloc_realloc(context, NULL, type, 1) ==> talloc(context, type); | |
| 333 talloc_realloc(context, NULL, type, N) ==> talloc_array(context, type, N); | |
| 334 talloc_realloc(context, ptr, type, 0) ==> talloc_free(ptr); | |
| 335 | |
| 336 The "context" argument is only used if "ptr" is NULL, otherwise it is | |
| 337 ignored. | |
| 338 | |
| 339 talloc_realloc() returns the new pointer, or NULL on failure. The call | |
| 340 will fail either due to a lack of memory, or because the pointer has | |
| 341 more than one parent (see talloc_reference()). | |
| 342 | |
| 343 | |
| 344 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 345 void *talloc_realloc_size(const void *context, void *ptr, size_t size); | |
| 346 | |
| 347 the talloc_realloc_size() function is useful when the type is not | |
| 348 known so the typesafe talloc_realloc() cannot be used. | |
| 349 | |
| 350 | |
| 351 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 352 void *talloc_steal(const void *new_ctx, const void *ptr); | |
| 353 | |
| 354 The talloc_steal() function changes the parent context of a talloc | |
| 355 pointer. It is typically used when the context that the pointer is | |
| 356 currently a child of is going to be freed and you wish to keep the | |
| 357 memory for a longer time. | |
| 358 | |
| 359 The talloc_steal() function returns the pointer that you pass it. It | |
| 360 does not have any failure modes. | |
| 361 | |
| 362 NOTE: It is possible to produce loops in the parent/child relationship | |
| 363 if you are not careful with talloc_steal(). No guarantees are provided | |
| 364 as to your sanity or the safety of your data if you do this. | |
| 365 | |
| 366 talloc_steal (new_ctx, NULL) will return NULL with no sideeffects. | |
| 367 | |
| 368 Note that if you try and call talloc_steal() on a pointer that has | |
| 369 more than one parent then the result is ambiguous. Talloc will choose | |
| 370 to remove the parent that is currently indicated by talloc_parent() | |
| 371 and replace it with the chosen parent. You will also get a message | |
| 372 like this via the talloc logging functions: | |
| 373 | |
| 374 WARNING: talloc_steal with references at some_dir/source/foo.c:123 | |
| 375 reference at some_dir/source/other.c:325 | |
| 376 reference at some_dir/source/third.c:121 | |
| 377 | |
| 378 To unambiguously change the parent of a pointer please see the | |
| 379 function talloc_reparent(). See the talloc_set_log_fn() documentation | |
| 380 for more information on talloc logging. | |
| 381 | |
| 382 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 383 void *talloc_reparent(const void *old_parent, const void *new_parent, const void
*ptr); | |
| 384 | |
| 385 The talloc_reparent() function changes the parent context of a talloc | |
| 386 pointer. It is typically used when the context that the pointer is | |
| 387 currently a child of is going to be freed and you wish to keep the | |
| 388 memory for a longer time. | |
| 389 | |
| 390 The talloc_reparent() function returns the pointer that you pass it. It | |
| 391 does not have any failure modes. | |
| 392 | |
| 393 The difference between talloc_reparent() and talloc_steal() is that | |
| 394 talloc_reparent() can specify which parent you wish to change. This is | |
| 395 useful when a pointer has multiple parents via references. | |
| 396 | |
| 397 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 398 void *talloc_parent(const void *ptr); | |
| 399 | |
| 400 The talloc_parent() function returns the current talloc parent. This | |
| 401 is usually the pointer under which this memory was originally created, | |
| 402 but it may have changed due to a talloc_steal() or talloc_reparent() | |
| 403 | |
| 404 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 405 size_t talloc_total_size(const void *ptr); | |
| 406 | |
| 407 The talloc_total_size() function returns the total size in bytes used | |
| 408 by this pointer and all child pointers. Mostly useful for debugging. | |
| 409 | |
| 410 Passing NULL is allowed, but it will only give a meaningful result if | |
| 411 talloc_enable_leak_report() or talloc_enable_leak_report_full() has | |
| 412 been called. | |
| 413 | |
| 414 | |
| 415 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 416 size_t talloc_total_blocks(const void *ptr); | |
| 417 | |
| 418 The talloc_total_blocks() function returns the total memory block | |
| 419 count used by this pointer and all child pointers. Mostly useful for | |
| 420 debugging. | |
| 421 | |
| 422 Passing NULL is allowed, but it will only give a meaningful result if | |
| 423 talloc_enable_leak_report() or talloc_enable_leak_report_full() has | |
| 424 been called. | |
| 425 | |
| 426 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 427 void talloc_report_depth_cb(const void *ptr, int depth, int max_depth, | |
| 428 void (*callback)(const void *ptr, | |
| 429 int depth, int max_depth, | |
| 430 int is_ref, | |
| 431 void *priv), | |
| 432 void *priv); | |
| 433 | |
| 434 This provides a more flexible reports than talloc_report(). It | |
| 435 will recursively call the callback for the entire tree of memory | |
| 436 referenced by the pointer. References in the tree are passed with | |
| 437 is_ref = 1 and the pointer that is referenced. | |
| 438 | |
| 439 You can pass NULL for the pointer, in which case a report is | |
| 440 printed for the top level memory context, but only if | |
| 441 talloc_enable_leak_report() or talloc_enable_leak_report_full() | |
| 442 has been called. | |
| 443 | |
| 444 The recursion is stopped when depth >= max_depth. | |
| 445 max_depth = -1 means only stop at leaf nodes. | |
| 446 | |
| 447 | |
| 448 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 449 void talloc_report_depth_file(const void *ptr, int depth, int max_depth, FILE *f
); | |
| 450 | |
| 451 This provides a more flexible reports than talloc_report(). It | |
| 452 will let you specify the depth and max_depth. | |
| 453 | |
| 454 | |
| 455 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 456 void talloc_report(const void *ptr, FILE *f); | |
| 457 | |
| 458 The talloc_report() function prints a summary report of all memory | |
| 459 used by ptr. One line of report is printed for each immediate child of | |
| 460 ptr, showing the total memory and number of blocks used by that child. | |
| 461 | |
| 462 You can pass NULL for the pointer, in which case a report is printed | |
| 463 for the top level memory context, but only if | |
| 464 talloc_enable_leak_report() or talloc_enable_leak_report_full() has | |
| 465 been called. | |
| 466 | |
| 467 | |
| 468 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 469 void talloc_report_full(const void *ptr, FILE *f); | |
| 470 | |
| 471 This provides a more detailed report than talloc_report(). It will | |
| 472 recursively print the ensire tree of memory referenced by the | |
| 473 pointer. References in the tree are shown by giving the name of the | |
| 474 pointer that is referenced. | |
| 475 | |
| 476 You can pass NULL for the pointer, in which case a report is printed | |
| 477 for the top level memory context, but only if | |
| 478 talloc_enable_leak_report() or talloc_enable_leak_report_full() has | |
| 479 been called. | |
| 480 | |
| 481 | |
| 482 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 483 void talloc_enable_leak_report(void); | |
| 484 | |
| 485 This enables calling of talloc_report(NULL, stderr) when the program | |
| 486 exits. In Samba4 this is enabled by using the --leak-report command | |
| 487 line option. | |
| 488 | |
| 489 For it to be useful, this function must be called before any other | |
| 490 talloc function as it establishes a "null context" that acts as the | |
| 491 top of the tree. If you don't call this function first then passing | |
| 492 NULL to talloc_report() or talloc_report_full() won't give you the | |
| 493 full tree printout. | |
| 494 | |
| 495 Here is a typical talloc report: | |
| 496 | |
| 497 talloc report on 'null_context' (total 267 bytes in 15 blocks) | |
| 498 libcli/auth/spnego_parse.c:55 contains 31 bytes in 2 blocks | |
| 499 libcli/auth/spnego_parse.c:55 contains 31 bytes in 2 blocks | |
| 500 iconv(UTF8,CP850) contains 42 bytes in 2 blocks | |
| 501 libcli/auth/spnego_parse.c:55 contains 31 bytes in 2 blocks | |
| 502 iconv(CP850,UTF8) contains 42 bytes in 2 blocks | |
| 503 iconv(UTF8,UTF-16LE) contains 45 bytes in 2 blocks | |
| 504 iconv(UTF-16LE,UTF8) contains 45 bytes in 2 blocks | |
| 505 | |
| 506 | |
| 507 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 508 void talloc_enable_leak_report_full(void); | |
| 509 | |
| 510 This enables calling of talloc_report_full(NULL, stderr) when the | |
| 511 program exits. In Samba4 this is enabled by using the | |
| 512 --leak-report-full command line option. | |
| 513 | |
| 514 For it to be useful, this function must be called before any other | |
| 515 talloc function as it establishes a "null context" that acts as the | |
| 516 top of the tree. If you don't call this function first then passing | |
| 517 NULL to talloc_report() or talloc_report_full() won't give you the | |
| 518 full tree printout. | |
| 519 | |
| 520 Here is a typical full report: | |
| 521 | |
| 522 full talloc report on 'root' (total 18 bytes in 8 blocks) | |
| 523 p1 contains 18 bytes in 7 blocks (ref 0) | |
| 524 r1 contains 13 bytes in 2 blocks (ref
0) | |
| 525 reference to: p2 | |
| 526 p2 contains 1 bytes in 1 blocks (ref
1) | |
| 527 x3 contains 1 bytes in 1 blocks (ref
0) | |
| 528 x2 contains 1 bytes in 1 blocks (ref
0) | |
| 529 x1 contains 1 bytes in 1 blocks (ref
0) | |
| 530 | |
| 531 | |
| 532 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 533 void talloc_enable_null_tracking(void); | |
| 534 | |
| 535 This enables tracking of the NULL memory context without enabling leak | |
| 536 reporting on exit. Useful for when you want to do your own leak | |
| 537 reporting call via talloc_report_null_full(); | |
| 538 | |
| 539 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 540 void talloc_disable_null_tracking(void); | |
| 541 | |
| 542 This disables tracking of the NULL memory context. | |
| 543 | |
| 544 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 545 (type *)talloc_zero(const void *ctx, type); | |
| 546 | |
| 547 The talloc_zero() macro is equivalent to:: | |
| 548 | |
| 549 ptr = talloc(ctx, type); | |
| 550 if (ptr) memset(ptr, 0, sizeof(type)); | |
| 551 | |
| 552 | |
| 553 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 554 void *talloc_zero_size(const void *ctx, size_t size) | |
| 555 | |
| 556 The talloc_zero_size() function is useful when you don't have a known type | |
| 557 | |
| 558 | |
| 559 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 560 void *talloc_memdup(const void *ctx, const void *p, size_t size); | |
| 561 | |
| 562 The talloc_memdup() function is equivalent to:: | |
| 563 | |
| 564 ptr = talloc_size(ctx, size); | |
| 565 if (ptr) memcpy(ptr, p, size); | |
| 566 | |
| 567 | |
| 568 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 569 char *talloc_strdup(const void *ctx, const char *p); | |
| 570 | |
| 571 The talloc_strdup() function is equivalent to:: | |
| 572 | |
| 573 ptr = talloc_size(ctx, strlen(p)+1); | |
| 574 if (ptr) memcpy(ptr, p, strlen(p)+1); | |
| 575 | |
| 576 This functions sets the name of the new pointer to the passed | |
| 577 string. This is equivalent to:: | |
| 578 | |
| 579 talloc_set_name_const(ptr, ptr) | |
| 580 | |
| 581 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 582 char *talloc_strndup(const void *t, const char *p, size_t n); | |
| 583 | |
| 584 The talloc_strndup() function is the talloc equivalent of the C | |
| 585 library function strndup() | |
| 586 | |
| 587 This functions sets the name of the new pointer to the passed | |
| 588 string. This is equivalent to: | |
| 589 talloc_set_name_const(ptr, ptr) | |
| 590 | |
| 591 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 592 char *talloc_append_string(const void *t, char *orig, const char *append); | |
| 593 | |
| 594 The talloc_append_string() function appends the given formatted | |
| 595 string to the given string. | |
| 596 | |
| 597 This function sets the name of the new pointer to the new | |
| 598 string. This is equivalent to:: | |
| 599 | |
| 600 talloc_set_name_const(ptr, ptr) | |
| 601 | |
| 602 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 603 char *talloc_vasprintf(const void *t, const char *fmt, va_list ap); | |
| 604 | |
| 605 The talloc_vasprintf() function is the talloc equivalent of the C | |
| 606 library function vasprintf() | |
| 607 | |
| 608 This functions sets the name of the new pointer to the new | |
| 609 string. This is equivalent to:: | |
| 610 | |
| 611 talloc_set_name_const(ptr, ptr) | |
| 612 | |
| 613 | |
| 614 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 615 char *talloc_asprintf(const void *t, const char *fmt, ...); | |
| 616 | |
| 617 The talloc_asprintf() function is the talloc equivalent of the C | |
| 618 library function asprintf() | |
| 619 | |
| 620 This functions sets the name of the new pointer to the new | |
| 621 string. This is equivalent to:: | |
| 622 | |
| 623 talloc_set_name_const(ptr, ptr) | |
| 624 | |
| 625 | |
| 626 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 627 char *talloc_asprintf_append(char *s, const char *fmt, ...); | |
| 628 | |
| 629 The talloc_asprintf_append() function appends the given formatted | |
| 630 string to the given string. | |
| 631 Use this varient when the string in the current talloc buffer may | |
| 632 have been truncated in length. | |
| 633 | |
| 634 This functions sets the name of the new pointer to the new | |
| 635 string. This is equivalent to:: | |
| 636 | |
| 637 talloc_set_name_const(ptr, ptr) | |
| 638 | |
| 639 | |
| 640 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 641 char *talloc_asprintf_append_buffer(char *s, const char *fmt, ...); | |
| 642 | |
| 643 The talloc_asprintf_append() function appends the given formatted | |
| 644 string to the end of the currently allocated talloc buffer. | |
| 645 Use this varient when the string in the current talloc buffer has | |
| 646 not been changed. | |
| 647 | |
| 648 This functions sets the name of the new pointer to the new | |
| 649 string. This is equivalent to:: | |
| 650 | |
| 651 talloc_set_name_const(ptr, ptr) | |
| 652 | |
| 653 | |
| 654 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 655 ((type *)talloc_array(const void *ctx, type, uint_t count); | |
| 656 | |
| 657 The talloc_array() macro is equivalent to:: | |
| 658 | |
| 659 (type *)talloc_size(ctx, sizeof(type) * count); | |
| 660 | |
| 661 except that it provides integer overflow protection for the multiply, | |
| 662 returning NULL if the multiply overflows. | |
| 663 | |
| 664 | |
| 665 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 666 void *talloc_array_size(const void *ctx, size_t size, uint_t count); | |
| 667 | |
| 668 The talloc_array_size() function is useful when the type is not | |
| 669 known. It operates in the same way as talloc_array(), but takes a size | |
| 670 instead of a type. | |
| 671 | |
| 672 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 673 (typeof(ptr)) talloc_array_ptrtype(const void *ctx, ptr, uint_t count); | |
| 674 | |
| 675 The talloc_ptrtype() macro should be used when you have a pointer to an array | |
| 676 and want to allocate memory of an array to point at with this pointer. When comp
iling | |
| 677 with gcc >= 3 it is typesafe. Note this is a wrapper of talloc_array_size() | |
| 678 and talloc_get_name() will return the current location in the source file. | |
| 679 and not the type. | |
| 680 | |
| 681 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 682 void *talloc_realloc_fn(const void *ctx, void *ptr, size_t size); | |
| 683 | |
| 684 This is a non-macro version of talloc_realloc(), which is useful | |
| 685 as libraries sometimes want a ralloc function pointer. A realloc() | |
| 686 implementation encapsulates the functionality of malloc(), free() and | |
| 687 realloc() in one call, which is why it is useful to be able to pass | |
| 688 around a single function pointer. | |
| 689 | |
| 690 | |
| 691 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 692 void *talloc_autofree_context(void); | |
| 693 | |
| 694 This is a handy utility function that returns a talloc context | |
| 695 which will be automatically freed on program exit. This can be used | |
| 696 to reduce the noise in memory leak reports. | |
| 697 | |
| 698 | |
| 699 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 700 void *talloc_check_name(const void *ptr, const char *name); | |
| 701 | |
| 702 This function checks if a pointer has the specified name. If it does | |
| 703 then the pointer is returned. It it doesn't then NULL is returned. | |
| 704 | |
| 705 | |
| 706 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 707 (type *)talloc_get_type(const void *ptr, type); | |
| 708 | |
| 709 This macro allows you to do type checking on talloc pointers. It is | |
| 710 particularly useful for void* private pointers. It is equivalent to | |
| 711 this:: | |
| 712 | |
| 713 (type *)talloc_check_name(ptr, #type) | |
| 714 | |
| 715 | |
| 716 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 717 talloc_set_type(const void *ptr, type); | |
| 718 | |
| 719 This macro allows you to force the name of a pointer to be a | |
| 720 particular type. This can be used in conjunction with | |
| 721 talloc_get_type() to do type checking on void* pointers. | |
| 722 | |
| 723 It is equivalent to this:: | |
| 724 | |
| 725 talloc_set_name_const(ptr, #type) | |
| 726 | |
| 727 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 728 talloc_get_size(const void *ctx); | |
| 729 | |
| 730 This function lets you know the amount of memory alloced so far by | |
| 731 this context. It does NOT account for subcontext memory. | |
| 732 This can be used to calculate the size of an array. | |
| 733 | |
| 734 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 735 void *talloc_find_parent_byname(const void *ctx, const char *name); | |
| 736 | |
| 737 Find a parent memory context of the current context that has the given | |
| 738 name. This can be very useful in complex programs where it may be | |
| 739 difficult to pass all information down to the level you need, but you | |
| 740 know the structure you want is a parent of another context. | |
| 741 | |
| 742 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 743 (type *)talloc_find_parent_bytype(ctx, type); | |
| 744 | |
| 745 Like talloc_find_parent_byname() but takes a type, making it typesafe. | |
| 746 | |
| 747 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 748 void talloc_set_log_fn(void (*log_fn)(const char *message)); | |
| 749 | |
| 750 This function sets a logging function that talloc will use for | |
| 751 warnings and errors. By default talloc will not print any warnings or | |
| 752 errors. | |
| 753 | |
| 754 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- | |
| 755 void talloc_set_log_stderr(void) | |
| 756 | |
| 757 This sets the talloc log function to write log messages to stderr | |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 2282793002:
Remove unused third_party/talloc (Closed)
