Crypto++ 8.9 Free C++ class library of cryptographic schemes

allocate.h
Go to the documentation of this file.
1 // allocate.h - written and placed in the public domain by Jeffrey Walton
2
3 // The functions in allocate.h and allocate.cpp were originally in misc.h
4 // and misc.cpp. They were extracted in September 2019 to sidestep a circular
5 // dependency with misc.h and secblock.h.
6
7 /// \file allocate.h
8 /// \brief Functions for allocating aligned buffers
9
10 #ifndef CRYPTOPP_ALLOCATE_H
11 #define CRYPTOPP_ALLOCATE_H
12
13 #include "config.h"
14 #include "cryptlib.h"
15
16 NAMESPACE_BEGIN(CryptoPP)
17
18 /// \brief Attempts to reclaim unused memory
19 /// \throw bad_alloc
20 /// \details In the normal course of running a program, a request for memory
21 /// normally succeeds. If a call to AlignedAllocate or UnalignedAllocate fails,
22 /// then CallNewHandler is called in n effort to recover. Internally,
23 /// CallNewHandler calls set_new_handler(nullptr) in an effort to free memory.
24 /// There is no guarantee CallNewHandler will be able to obtain more memory so
25 /// an allocation succeeds. If the call to set_new_handler fails, then CallNewHandler
26 /// throws a bad_alloc exception.
27 /// \throw bad_alloc on failure
28 /// \since Crypto++ 5.0
29 /// \sa AlignedAllocate, AlignedDeallocate, UnalignedAllocate, UnalignedDeallocate
30 CRYPTOPP_DLL void CRYPTOPP_API CallNewHandler();
31
32 /// \brief Allocates a buffer on 16-byte boundary
33 /// \param size the size of the buffer
34 /// \details AlignedAllocate is primarily used when the data will be
35 /// processed by SSE, NEON, ARMv8 or PowerPC instructions. The assembly
36 /// language routines rely on the alignment. If the alignment is not
37 /// respected, then a SIGBUS could be generated on Unix and Linux, and an
38 /// EXCEPTION_DATATYPE_MISALIGNMENT could be generated on Windows.
39 /// \details Formerly, AlignedAllocate and AlignedDeallocate were only
40 /// available on certain platforms when CRYTPOPP_DISABLE_ASM was not in
41 /// effect. However, Android and iOS debug simulator builds got into a
42 /// state where the aligned allocator was not available and caused link
43 /// failures.
44 /// \since AlignedAllocate for SIMD since Crypto++ 1.0, AlignedAllocate
45 /// for all builds since Crypto++ 8.1
46 /// \sa AlignedDeallocate, UnalignedAllocate, UnalignedDeallocate, CallNewHandler,
47 /// <A HREF="http://github.com/weidai11/cryptopp/issues/779">Issue 779</A>
48 CRYPTOPP_DLL void* CRYPTOPP_API AlignedAllocate(size_t size);
49
50 /// \brief Frees a buffer allocated with AlignedAllocate
51 /// \param ptr the buffer to free
52 /// \since AlignedDeallocate for SIMD since Crypto++ 1.0, AlignedAllocate
53 /// for all builds since Crypto++ 8.1
54 /// \sa AlignedAllocate, UnalignedAllocate, UnalignedDeallocate, CallNewHandler,
55 /// <A HREF="http://github.com/weidai11/cryptopp/issues/779">Issue 779</A>
56 CRYPTOPP_DLL void CRYPTOPP_API AlignedDeallocate(void *ptr);
57
58 /// \brief Allocates a buffer
59 /// \param size the size of the buffer
60 /// \since Crypto++ 1.0
61 /// \sa AlignedAllocate, AlignedDeallocate, UnalignedDeallocate, CallNewHandler,
62 /// <A HREF="http://github.com/weidai11/cryptopp/issues/779">Issue 779</A>
63 CRYPTOPP_DLL void * CRYPTOPP_API UnalignedAllocate(size_t size);
64
65 /// \brief Frees a buffer allocated with UnalignedAllocate
66 /// \param ptr the buffer to free
67 /// \since Crypto++ 1.0
68 /// \sa AlignedAllocate, AlignedDeallocate, UnalignedAllocate, CallNewHandler,
69 /// <A HREF="http://github.com/weidai11/cryptopp/issues/779">Issue 779</A>
70 CRYPTOPP_DLL void CRYPTOPP_API UnalignedDeallocate(void *ptr);
71
72 NAMESPACE_END
73
74 #endif // CRYPTOPP_ALLOCATE_H
AlignedDeallocate
CRYPTOPP_DLL void AlignedDeallocate(void *ptr)
Frees a buffer allocated with AlignedAllocate.
CallNewHandler
CRYPTOPP_DLL void CallNewHandler()
Attempts to reclaim unused memory.
UnalignedAllocate
CRYPTOPP_DLL void * UnalignedAllocate(size_t size)
Allocates a buffer.
UnalignedDeallocate
CRYPTOPP_DLL void UnalignedDeallocate(void *ptr)
Frees a buffer allocated with UnalignedAllocate.
AlignedAllocate
CRYPTOPP_DLL void * AlignedAllocate(size_t size)
Allocates a buffer on 16-byte boundary.
config.h
Library configuration file.
CRYPTOPP_API
#define CRYPTOPP_API
Win32 calling convention.
Definition: config_dll.h:119
cryptlib.h
Abstract base classes that provide a uniform interface to this library.
CryptoPP
Crypto++ library namespace.