diff --git a/include/secp256k1_preallocated.h b/include/secp256k1_preallocated.h index 77426ee786fd5..0fb64a5431f8a 100644 --- a/include/secp256k1_preallocated.h +++ b/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)