secp256k1_preallocated.h (6442B)
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 haskellsecp256k1_v0_1_0_context_preallocated_destroy (in this 20 * module) instead of haskellsecp256k1_v0_1_0_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 haskellsecp256k1_v0_1_0_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 haskellsecp256k1_v0_1_0_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 haskellsecp256k1_v0_1_0_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 haskellsecp256k1_v0_1_0_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 haskellsecp256k1_v0_1_0_context_preallocated_size(flags) 58 * bytes, as detailed above. 59 * flags: which parts of the context to initialize. 60 * 61 * See haskellsecp256k1_v0_1_0_context_create (in secp256k1.h) for further details. 62 * 63 * See also haskellsecp256k1_v0_1_0_context_randomize (in secp256k1.h) 64 * and haskellsecp256k1_v0_1_0_context_preallocated_destroy. 65 */ 66 SECP256K1_API haskellsecp256k1_v0_1_0_context *haskellsecp256k1_v0_1_0_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 haskellsecp256k1_v0_1_0_context_preallocated_clone_size( 78 const haskellsecp256k1_v0_1_0_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 haskellsecp256k1_v0_1_0_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 * haskellsecp256k1_v0_1_0_context_preallocated_create for details. 90 * 91 * Cloning haskellsecp256k1_v0_1_0_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 haskellsecp256k1_v0_1_0_context_static). 96 * In: prealloc: pointer to a rewritable contiguous block of memory of 97 * size at least haskellsecp256k1_v0_1_0_context_preallocated_size(flags) 98 * bytes, as detailed above. 99 */ 100 SECP256K1_API haskellsecp256k1_v0_1_0_context *haskellsecp256k1_v0_1_0_context_preallocated_clone( 101 const haskellsecp256k1_v0_1_0_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 * haskellsecp256k1_v0_1_0_context_preallocated_create or haskellsecp256k1_v0_1_0_context_preallocated_clone. 112 * If the context has instead been created using haskellsecp256k1_v0_1_0_context_create or 113 * haskellsecp256k1_v0_1_0_context_clone, the behaviour is undefined. In that case, 114 * haskellsecp256k1_v0_1_0_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 haskellsecp256k1_v0_1_0_context_preallocated_create or 119 * haskellsecp256k1_v0_1_0_context_preallocated_clone. 120 * 121 * Args: ctx: pointer to a context to destroy, constructed using 122 * haskellsecp256k1_v0_1_0_context_preallocated_create or 123 * haskellsecp256k1_v0_1_0_context_preallocated_clone 124 * (i.e., not haskellsecp256k1_v0_1_0_context_static). 125 */ 126 SECP256K1_API void haskellsecp256k1_v0_1_0_context_preallocated_destroy( 127 haskellsecp256k1_v0_1_0_context *ctx 128 ) SECP256K1_ARG_NONNULL(1); 129 130 #ifdef __cplusplus 131 } 132 #endif 133 134 #endif /* SECP256K1_PREALLOCATED_H */