Changeset 746 for vendor/current/lib/talloc/talloc.h

Timestamp:

Nov 27, 2012, 4:56:06 PM (13 years ago)

Author:

Silvan Scherrer

Message:

Samba Server: updated vendor to 3.6.9

File:

• vendor/current/lib/talloc/talloc.h (modified) (10 diffs)

vendor/current/lib/talloc/talloc.h

@@ -174 +174 @@
  * no modifications and return -1.
  *
- * If this pointer has an additional parent when talloc_free() is called
- * then the memory is not actually released, but instead the most
- * recently established parent is destroyed. See talloc_reference() for
- * details on establishing additional parents.
- *
- * For more control on which parent is removed, see talloc_unlink()
- *
- * talloc_free() operates recursively on its children.
- *
- * From the 2.0 version of talloc, as a special case, talloc_free() is
- * refused on pointers that have more than one parent, as talloc would
- * have no way of knowing which parent should be removed. To free a
+ * From version 2.0 and onwards, as a special case, talloc_free() is
+ * refused on pointers that have more than one parent associated, as talloc
+ * would have no way of knowing which parent should be removed. This is
+ * different from older versions in the sense that always the reference to
+ * the most recently established parent has been destroyed. Hence to free a
  * pointer that has more than one parent please use talloc_unlink().
  *
@@ -201 +194 @@
  * talloc_set_log_stderr() for more information on talloc logging
  * functions.
+ *
+ * talloc_free() operates recursively on its children.
  *
  * @param[in]  ptr      The chunk to be freed.
@@ -234 +229 @@
  * talloc_free()s only the children, not the context itself.
  *
- * @param[in]  ptr      The chunk that you want to free the children of.
+ * A NULL argument is handled as no-op.
+ *
+ * @param[in]  ptr      The chunk that you want to free the children of
+ *                      (NULL is allowed too)
  */
 void talloc_free_children(void *ptr);
@@ -403 +401 @@
  * @param[in]  new_ctx  The new parent context.
  *
- * @param[in]  ptr      Pointer to the talloc chunk to move.
+ * @param[in]  pptr     Pointer to the talloc chunk to move.
  *
  * @return              The pointer of the talloc chunk it has been moved to,
  *                      NULL on error.
  */
-void *talloc_move(const void *new_ctx, const void *ptr);
-#else
-#define talloc_move(ctx, ptr) (_TALLOC_TYPEOF(*(ptr)))_talloc_move((ctx),(void *)(ptr))
+void *talloc_move(const void *new_ctx, void **pptr);
+#else
+#define talloc_move(ctx, pptr) (_TALLOC_TYPEOF(*(pptr)))_talloc_move((ctx),(void *)(pptr))
 void *_talloc_move(const void *new_ctx, const void *pptr);
 #endif
@@ -703 +701 @@
  * @brief Assign a type to a talloc chunk.
  *
- * This macro allows you to force the name of a pointer to be a particular type.
- * This can be used in conjunction with talloc_get_type() to do type checking on
- * void* pointers.
+ * This macro allows you to force the name of a pointer to be of a particular
+ * type. This can be used in conjunction with talloc_get_type() to do type
+ * checking on void* pointers.
  *
  * It is equivalent to this:
@@ -906 +904 @@
  *   cause this pointer to be freed if it runs out of parents.
  *
- * - you can talloc_free() the pointer itself. That will destroy the
- *   most recently established parent to the pointer and leave the
- *   pointer as a child of its current parent.
+ * - you can talloc_free() the pointer itself if it has at maximum one
+ *   parent. This behaviour has been changed since the release of version
+ *   2.0. Further informations in the description of "talloc_free".
  *
  * For more control on which parent to remove, see talloc_unlink()
@@ -943 +941 @@
  * a direct parent of ptr.
  *
- * Usually you can just use talloc_free() instead of talloc_unlink(), but
- * sometimes it is useful to have the additional control on which parent is
- * removed.
+ * You can just use talloc_free() instead of talloc_unlink() if there
+ * is at maximum one parent. This behaviour has been changed since the
+ * release of version 2.0. Further informations in the description of
+ * "talloc_free".
  *
  * @param[in]  context  The talloc parent to remove.
@@ -993 +992 @@
  * @brief Get the size of a talloc chunk.
  *
- * This function lets you know the amount of memory alloced so far by
+ * This function lets you know the amount of memory allocated so far by
  * this context. It does NOT account for subcontext memory.
  * This can be used to calculate the size of an array.
@@ -1454 +1453 @@
  *
  * This function appends the given formatted string to the given string. Use
- * this varient when the string in the current talloc buffer may have been
+ * this variant when the string in the current talloc buffer may have been
  * truncated in length.
  *
@@ -1552 +1551 @@
  *
  * This provides a more detailed report than talloc_report(). It will
- * recursively print the ensire tree of memory referenced by the
+ * recursively print the entire tree of memory referenced by the
  * pointer. References in the tree are shown by giving the name of the
  * pointer that is referenced.