Explain caller's obligations for preallocated memory

Author: real-or-random

include/secp256k1_preallocated.h

@@ -12,7 +12,14 @@ extern "C" {
  * functions for creating, cloning, and destroying secp256k1 context objects in a
  * contiguous fixed-size block of memory provided by the caller.
  *
- * It is guaranteed that functions in this module will not call malloc or its
+ * Context objects created by functions in this module can be used like contexts
+ * objects created by functions in secp256k1.h, i.e., they can be passed to any
+ * API function that excepts a context object (see secp256k1.h for details). The
+ * only exception is that context objects created by functions in this module
+ * must be destroyed using secp256k1_context_preallocated_destroy (in this
+ * module) instead of secp256k1_context_destroy (in secp256k1.h).
+ *
+ * It is guaranteed that functions in by this module will not call malloc or its
  * friends realloc, calloc, and free.
  */
 
@@ -30,15 +37,29 @@ SECP256K1_API size_t secp256k1_context_preallocated_size(
 ) SECP256K1_WARN_UNUSED_RESULT;
 
 /** Create a secp256k1 context object in caller-provided memory.
+ *
+ *  The caller must provide a pointer to a rewritable contiguous block of memory
+ *  of size at least secp256k1_context_preallocated_size(flags) bytes, suitably
+ *  aligned to hold an object of any type.
+ *
+ *  The block of memory is exclusively owned by the created context object during
+ *  the lifetime of this context object, which begins with the call to this
+ *  function and ends when a call to secp256k1_context_preallocated_destroy
+ *  (which destroys the context object again) returns. During the lifetime of the
+ *  context object, the caller is obligated not to access this block of memory,
+ *  i.e., the caller may not read or write the memory, e.g., by copying the memory
+ *  contents to a different location or trying to create a second context object
+ *  in the memory. In simpler words, the prealloc pointer (or any pointer derived
+ *  from it) should not be used during the lifetime of the context object.
  *
  *  Returns: a newly created context object.
  *  In:      prealloc: a pointer to a rewritable contiguous block of memory of
  *                     size at least secp256k1_context_preallocated_size(flags)
- *                     bytes, suitably aligned to hold an object of any type
- *                     (cannot be NULL)
+ *                     bytes, as detailed above (cannot be NULL)
  *           flags:    which parts of the context to initialize.
  *
- *  See also secp256k1_context_randomize.
+ *  See also secp256k1_context_randomize (in secp256k1.h)
+ *  and secp256k1_context_preallocated_destroy.
  */
 SECP256K1_API secp256k1_context* secp256k1_context_preallocated_create(
     void* prealloc,
@@ -48,9 +69,6 @@ SECP256K1_API secp256k1_context* secp256k1_context_preallocated_create(
 /** Determine the memory size of a secp256k1 context object to be copied into
  *  caller-provided memory.
  *
- *  The purpose of this function is to determine how much memory must be provided
- *  to secp256k1_context_preallocated_clone when copying the context ctx.
- *
  *  Returns: the required size of the caller-provided memory block.
  *  In:      ctx: an existing context to copy (cannot be NULL)
  */
@@ -59,13 +77,20 @@ SECP256K1_API size_t secp256k1_context_preallocated_clone_size(
 ) SECP256K1_ARG_NONNULL(1) SECP256K1_WARN_UNUSED_RESULT;
 
 /** Copy a secp256k1 context object into caller-provided memory.
+ *
+ *  The caller must provide a pointer to a rewritable contiguous block of memory
+ *  of size at least secp256k1_context_preallocated_size(flags) bytes, suitably
+ *  aligned to hold an object of any type.
+ *
+ *  The block of memory is exclusively owned by the created context object during
+ *  the lifetime of this context object, see the description of
+ *  secp256k1_context_preallocated_create for details.
  *
  *  Returns: a newly created context object.
  *  Args:    ctx:      an existing context to copy (cannot be NULL)
  *  In:      prealloc: a pointer to a rewritable contiguous block of memory of
  *                     size at least secp256k1_context_preallocated_size(flags)
- *                     bytes, suitably aligned to hold an object of any type
- *                     (cannot be NULL)
+ *                     bytes, as detailed above (cannot be NULL)
  */
 SECP256K1_API secp256k1_context* secp256k1_context_preallocated_clone(
     const secp256k1_context* ctx,
@@ -83,6 +108,11 @@ SECP256K1_API secp256k1_context* secp256k1_context_preallocated_clone(
  *  secp256k1_context_clone, the behaviour is undefined. In that case,
  *  secp256k1_context_destroy must be used instead.
  *
+ *  If required, it is the responsibility of the caller to deallocate the block
+ *  of memory properly after this function returns, e.g., by calling free on the
+ *  preallocated pointer given to secp256k1_context_preallocated_create or
+ *  secp256k1_context_preallocated_clone.
+ *
  *  Args:   ctx: an existing context to destroy, constructed using
  *               secp256k1_context_preallocated_create or
  *               secp256k1_context_preallocated_clone (cannot be NULL)