allocate.h File Reference

Functions for allocating aligned buffers. More...

Go to the source code of this file.

## Functions

CRYPTOPP_DLL void | CallNewHandler ()
| Attempts to reclaim unused memory. More...
CRYPTOPP_DLL void * | AlignedAllocate (size_t size)
| Allocates a buffer on 16-byte boundary. More...
CRYPTOPP_DLL void | AlignedDeallocate (void *ptr)
| Frees a buffer allocated with AlignedAllocate. More...
CRYPTOPP_DLL void * | UnalignedAllocate (size_t size)
| Allocates a buffer. More...
CRYPTOPP_DLL void | UnalignedDeallocate (void *ptr)
| Frees a buffer allocated with UnalignedAllocate. More...

## Detailed Description

Functions for allocating aligned buffers.

Definition in file allocate.h.

## Function Documentation

## CallNewHandler()

CRYPTOPP_DLL void CallNewHandler | ( |  | ) |

Attempts to reclaim unused memory.

Exceptions

  bad_alloc |

In the normal course of running a program, a request for memory normally succeeds. If a call to AlignedAllocate or UnalignedAllocate fails, then CallNewHandler is called in n effort to recover. Internally, CallNewHandler calls set_new_handler(nullptr) in an effort to free memory. There is no guarantee CallNewHandler will be able to obtain more memory so an allocation succeeds. If the call to set_new_handler fails, then CallNewHandler throws a bad_alloc exception.

Exceptions

  bad_alloc | on failure

Since
  Crypto++ 5.0

See also
  AlignedAllocate, AlignedDeallocate, UnalignedAllocate, UnalignedDeallocate

## AlignedAllocate()

CRYPTOPP_DLL void* AlignedAllocate | ( | size_t | size | ) |

Allocates a buffer on 16-byte boundary.

Parameters

  size | the size of the buffer

AlignedAllocate is primarily used when the data will be processed by SSE, NEON, ARMv8 or PowerPC instructions. The assembly language routines rely on the alignment. If the alignment is not respected, then a SIGBUS could be generated on Unix and Linux, and an EXCEPTION_DATATYPE_MISALIGNMENT could be generated on Windows.

Formerly, AlignedAllocate and AlignedDeallocate were only available on certain platforms when CRYTPOPP_DISABLE_ASM was not in effect. However, Android and iOS debug simulator builds got into a state where the aligned allocator was not available and caused link failures.

Since
  AlignedAllocate for SIMD since Crypto++ 1.0, AlignedAllocate for all builds since Crypto++ 8.1

See also
  AlignedDeallocate, UnalignedAllocate, UnalignedDeallocate, CallNewHandler, Issue 779

## AlignedDeallocate()

CRYPTOPP_DLL void AlignedDeallocate | ( | void * | ptr | ) |

Frees a buffer allocated with AlignedAllocate.

Parameters

  ptr | the buffer to free

Since
  AlignedDeallocate for SIMD since Crypto++ 1.0, AlignedAllocate for all builds since Crypto++ 8.1

See also
  AlignedAllocate, UnalignedAllocate, UnalignedDeallocate, CallNewHandler, Issue 779

## UnalignedAllocate()

CRYPTOPP_DLL void* UnalignedAllocate | ( | size_t | size | ) |

Allocates a buffer.

Parameters

  size | the size of the buffer

Since
  Crypto++ 1.0

See also
  AlignedAllocate, AlignedDeallocate, UnalignedDeallocate, CallNewHandler, Issue 779

## UnalignedDeallocate()

CRYPTOPP_DLL void UnalignedDeallocate | ( | void * | ptr | ) |

Frees a buffer allocated with UnalignedAllocate.

Parameters

  ptr | the buffer to free

Since
  Crypto++ 1.0

See also
  AlignedAllocate, AlignedDeallocate, UnalignedAllocate, CallNewHandler, Issue 779