include/cryptopp/allocate.h

0001 // allocate.h - written and placed in the public domain by Jeffrey Walton

0002
0003 // The functions in allocate.h and allocate.cpp were originally in misc.h

0004 // and misc.cpp. They were extracted in September 2019 to sidestep a circular

0005 // dependency with misc.h and secblock.h.

0006
0007 /// \file allocate.h

0008 /// \brief Functions for allocating aligned buffers

0009
0010 #ifndef CRYPTOPP_ALLOCATE_H
0011 #define CRYPTOPP_ALLOCATE_H
0012
0013 #include "config.h"
0014 #include "cryptlib.h"
0015
0016 NAMESPACE_BEGIN(CryptoPP)
0017
0018 /// \brief Attempts to reclaim unused memory

0019 /// \throw bad_alloc

0020 /// \details In the normal course of running a program, a request for memory

0021 ///  normally succeeds. If a call to AlignedAllocate or UnalignedAllocate fails,

0022 ///  then CallNewHandler is called in n effort to recover. Internally,

0023 ///  CallNewHandler calls set_new_handler(nullptr) in an effort to free memory.

0024 ///  There is no guarantee CallNewHandler will be able to obtain more memory so

0025 ///  an allocation succeeds. If the call to set_new_handler fails, then CallNewHandler

0026 ///  throws a bad_alloc exception.

0027 /// \throw bad_alloc on failure

0028 /// \since Crypto++ 5.0

0029 /// \sa AlignedAllocate, AlignedDeallocate, UnalignedAllocate, UnalignedDeallocate

0030 CRYPTOPP_DLL void CRYPTOPP_API CallNewHandler();
0031
0032 /// \brief Allocates a buffer on 16-byte boundary

0033 /// \param size the size of the buffer

0034 /// \details AlignedAllocate is primarily used when the data will be

0035 ///  processed by SSE, NEON, ARMv8 or PowerPC instructions. The assembly

0036 ///  language routines rely on the alignment. If the alignment is not

0037 ///  respected, then a SIGBUS could be generated on Unix and Linux, and an

0038 ///  EXCEPTION_DATATYPE_MISALIGNMENT could be generated on Windows.

0039 /// \details Formerly, AlignedAllocate and AlignedDeallocate were only

0040 ///  available on certain platforms when CRYTPOPP_DISABLE_ASM was not in

0041 ///  effect. However, Android and iOS debug simulator builds got into a

0042 ///  state where the aligned allocator was not available and caused link

0043 ///  failures.

0044 /// \since AlignedAllocate for SIMD since Crypto++ 1.0, AlignedAllocate

0045 ///  for all builds since Crypto++ 8.1

0046 /// \sa AlignedDeallocate, UnalignedAllocate, UnalignedDeallocate, CallNewHandler,

0047 ///  <A HREF="http://github.com/weidai11/cryptopp/issues/779">Issue 779</A>

0048 CRYPTOPP_DLL void* CRYPTOPP_API AlignedAllocate(size_t size);
0049
0050 /// \brief Frees a buffer allocated with AlignedAllocate

0051 /// \param ptr the buffer to free

0052 /// \since AlignedDeallocate for SIMD since Crypto++ 1.0, AlignedAllocate

0053 ///  for all builds since Crypto++ 8.1

0054 /// \sa AlignedAllocate, UnalignedAllocate, UnalignedDeallocate, CallNewHandler,

0055 ///  <A HREF="http://github.com/weidai11/cryptopp/issues/779">Issue 779</A>

0056 CRYPTOPP_DLL void CRYPTOPP_API AlignedDeallocate(void *ptr);
0057
0058 /// \brief Allocates a buffer

0059 /// \param size the size of the buffer

0060 /// \since Crypto++ 1.0

0061 /// \sa AlignedAllocate, AlignedDeallocate, UnalignedDeallocate, CallNewHandler,

0062 ///  <A HREF="http://github.com/weidai11/cryptopp/issues/779">Issue 779</A>

0063 CRYPTOPP_DLL void * CRYPTOPP_API UnalignedAllocate(size_t size);
0064
0065 /// \brief Frees a buffer allocated with UnalignedAllocate

0066 /// \param ptr the buffer to free

0067 /// \since Crypto++ 1.0

0068 /// \sa AlignedAllocate, AlignedDeallocate, UnalignedAllocate, CallNewHandler,

0069 ///  <A HREF="http://github.com/weidai11/cryptopp/issues/779">Issue 779</A>

0070 CRYPTOPP_DLL void CRYPTOPP_API UnalignedDeallocate(void *ptr);
0071
0072 NAMESPACE_END
0073
0074 #endif  // CRYPTOPP_ALLOCATE_H