github.com/ethereum/go-ethereum@v1.16.1/crypto/secp256k1/libsecp256k1/include/secp256k1_preallocated.h (about)

     1  #ifndef SECP256K1_PREALLOCATED_H
     2  #define SECP256K1_PREALLOCATED_H
     3  
     4  #include "secp256k1.h"
     5  
     6  #ifdef __cplusplus
     7  extern "C" {
     8  #endif
     9  
    10  /* The module provided by this header file is intended for settings in which it
    11   * is not possible or desirable to rely on dynamic memory allocation. It provides
    12   * functions for creating, cloning, and destroying secp256k1 context objects in a
    13   * contiguous fixed-size block of memory provided by the caller.
    14   *
    15   * Context objects created by functions in this module can be used like contexts
    16   * objects created by functions in secp256k1.h, i.e., they can be passed to any
    17   * API function that expects a context object (see secp256k1.h for details). The
    18   * only exception is that context objects created by functions in this module
    19   * must be destroyed using secp256k1_context_preallocated_destroy (in this
    20   * module) instead of secp256k1_context_destroy (in secp256k1.h).
    21   *
    22   * It is guaranteed that functions in this module will not call malloc or its
    23   * friends realloc, calloc, and free.
    24   */
    25  
    26  /** Determine the memory size of a secp256k1 context object to be created in
    27   *  caller-provided memory.
    28   *
    29   *  The purpose of this function is to determine how much memory must be provided
    30   *  to secp256k1_context_preallocated_create.
    31   *
    32   *  Returns: the required size of the caller-provided memory block
    33   *  In:      flags:    which parts of the context to initialize.
    34   */
    35  SECP256K1_API size_t secp256k1_context_preallocated_size(
    36      unsigned int flags
    37  ) SECP256K1_WARN_UNUSED_RESULT;
    38  
    39  /** Create a secp256k1 context object in caller-provided memory.
    40   *
    41   *  The caller must provide a pointer to a rewritable contiguous block of memory
    42   *  of size at least secp256k1_context_preallocated_size(flags) bytes, suitably
    43   *  aligned to hold an object of any type.
    44   *
    45   *  The block of memory is exclusively owned by the created context object during
    46   *  the lifetime of this context object, which begins with the call to this
    47   *  function and ends when a call to secp256k1_context_preallocated_destroy
    48   *  (which destroys the context object again) returns. During the lifetime of the
    49   *  context object, the caller is obligated not to access this block of memory,
    50   *  i.e., the caller may not read or write the memory, e.g., by copying the memory
    51   *  contents to a different location or trying to create a second context object
    52   *  in the memory. In simpler words, the prealloc pointer (or any pointer derived
    53   *  from it) should not be used during the lifetime of the context object.
    54   *
    55   *  Returns: pointer to newly created context object.
    56   *  In:      prealloc: pointer to a rewritable contiguous block of memory of
    57   *                     size at least secp256k1_context_preallocated_size(flags)
    58   *                     bytes, as detailed above.
    59   *           flags:    which parts of the context to initialize.
    60   *
    61   *  See secp256k1_context_create (in secp256k1.h) for further details.
    62   *
    63   *  See also secp256k1_context_randomize (in secp256k1.h)
    64   *  and secp256k1_context_preallocated_destroy.
    65   */
    66  SECP256K1_API secp256k1_context *secp256k1_context_preallocated_create(
    67      void *prealloc,
    68      unsigned int flags
    69  ) SECP256K1_ARG_NONNULL(1) SECP256K1_WARN_UNUSED_RESULT;
    70  
    71  /** Determine the memory size of a secp256k1 context object to be copied into
    72   *  caller-provided memory.
    73   *
    74   *  Returns: the required size of the caller-provided memory block.
    75   *  In:      ctx: pointer to a context to copy.
    76   */
    77  SECP256K1_API size_t secp256k1_context_preallocated_clone_size(
    78      const secp256k1_context *ctx
    79  ) SECP256K1_ARG_NONNULL(1) SECP256K1_WARN_UNUSED_RESULT;
    80  
    81  /** Copy a secp256k1 context object into caller-provided memory.
    82   *
    83   *  The caller must provide a pointer to a rewritable contiguous block of memory
    84   *  of size at least secp256k1_context_preallocated_size(flags) bytes, suitably
    85   *  aligned to hold an object of any type.
    86   *
    87   *  The block of memory is exclusively owned by the created context object during
    88   *  the lifetime of this context object, see the description of
    89   *  secp256k1_context_preallocated_create for details.
    90   *
    91   *  Cloning secp256k1_context_static is not possible, and should not be emulated by
    92   *  the caller (e.g., using memcpy). Create a new context instead.
    93   *
    94   *  Returns: pointer to a newly created context object.
    95   *  Args:    ctx:      pointer to a context to copy (not secp256k1_context_static).
    96   *  In:      prealloc: pointer to a rewritable contiguous block of memory of
    97   *                     size at least secp256k1_context_preallocated_size(flags)
    98   *                     bytes, as detailed above.
    99   */
   100  SECP256K1_API secp256k1_context *secp256k1_context_preallocated_clone(
   101      const secp256k1_context *ctx,
   102      void *prealloc
   103  ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_WARN_UNUSED_RESULT;
   104  
   105  /** Destroy a secp256k1 context object that has been created in
   106   *  caller-provided memory.
   107   *
   108   *  The context pointer may not be used afterwards.
   109   *
   110   *  The context to destroy must have been created using
   111   *  secp256k1_context_preallocated_create or secp256k1_context_preallocated_clone.
   112   *  If the context has instead been created using secp256k1_context_create or
   113   *  secp256k1_context_clone, the behaviour is undefined. In that case,
   114   *  secp256k1_context_destroy must be used instead.
   115   *
   116   *  If required, it is the responsibility of the caller to deallocate the block
   117   *  of memory properly after this function returns, e.g., by calling free on the
   118   *  preallocated pointer given to secp256k1_context_preallocated_create or
   119   *  secp256k1_context_preallocated_clone.
   120   *
   121   *  Args:   ctx: pointer to a context to destroy, constructed using
   122   *               secp256k1_context_preallocated_create or
   123   *               secp256k1_context_preallocated_clone
   124   *               (i.e., not secp256k1_context_static).
   125   */
   126  SECP256K1_API void secp256k1_context_preallocated_destroy(
   127      secp256k1_context *ctx
   128  ) SECP256K1_ARG_NONNULL(1);
   129  
   130  #ifdef __cplusplus
   131  }
   132  #endif
   133  
   134  #endif /* SECP256K1_PREALLOCATED_H */