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 */
135