include.secp256k1_preollocated source code

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