Crypto++  8.8
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
CRYPTOPP_DLL void AlignedDeallocate(void *ptr)
Frees a buffer allocated with AlignedAllocate.
CRYPTOPP_DLL void CallNewHandler()
Attempts to reclaim unused memory.
CRYPTOPP_DLL void * UnalignedAllocate(size_t size)
Allocates a buffer.
CRYPTOPP_DLL void UnalignedDeallocate(void *ptr)
Frees a buffer allocated with UnalignedAllocate.
CRYPTOPP_DLL void * AlignedAllocate(size_t size)
Allocates a buffer on 16-byte boundary.
Library configuration file.
#define CRYPTOPP_API
Win32 calling convention.
Definition: config_dll.h:119
Abstract base classes that provide a uniform interface to this library.
Crypto++ library namespace.