plMemoryUtils Class Reference

This class provides functions to work on raw memory. More...

#include <MemoryUtils.h>

Public Types
using	ConstructorFunction = void (*)(void* pDestination)
using	CopyConstructorFunction = void (*)(void* pDestination, const void* pSource)
using	DestructorFunction = void (*)(void* pDestination)

Public Member Functions
template<plConstructionMode mode, typename T >
PL_ALWAYS_INLINE void	Construct (T *pDestination, size_t uiCount)
template<plConstructionMode mode, typename T >
PL_ALWAYS_INLINE plMemoryUtils::ConstructorFunction	MakeConstructorFunction ()
template<typename Destination , typename Source >
PL_ALWAYS_INLINE void	CopyConstruct (Destination *pDestination, const Source &copy, size_t uiCount)
template<typename T >
PL_ALWAYS_INLINE void	CopyConstructArray (T *pDestination, const T *pSource, size_t uiCount)
template<typename T >
PL_ALWAYS_INLINE plMemoryUtils::CopyConstructorFunction	MakeCopyConstructorFunction ()
template<typename T >
PL_ALWAYS_INLINE void	MoveConstruct (T *pDestination, T &&source)
template<typename T >
PL_ALWAYS_INLINE void	MoveConstruct (T *pDestination, T *pSource, size_t uiCount)
template<typename Destination , typename Source >
PL_ALWAYS_INLINE void	CopyOrMoveConstruct (Destination *pDestination, Source &&source)
template<typename T >
PL_ALWAYS_INLINE void	RelocateConstruct (T *pDestination, T *pSource, size_t uiCount)
template<typename T >
PL_ALWAYS_INLINE void	Destruct (T *pDestination, size_t uiCount)
template<typename T >
PL_ALWAYS_INLINE plMemoryUtils::DestructorFunction	MakeDestructorFunction ()
template<typename T >
PL_ALWAYS_INLINE void	Copy (T *pDestination, const T *pSource, size_t uiCount)
template<typename T >
PL_ALWAYS_INLINE void	CopyOverlapped (T *pDestination, const T *pSource, size_t uiCount)
template<typename T >
PL_ALWAYS_INLINE void	Relocate (T *pDestination, T *pSource, size_t uiCount)
template<typename T >
PL_ALWAYS_INLINE void	RelocateOverlapped (T *pDestination, T *pSource, size_t uiCount)
template<typename T >
PL_ALWAYS_INLINE void	Prepend (T *pDestination, const T &source, size_t uiCount)
template<typename T >
PL_ALWAYS_INLINE void	Prepend (T *pDestination, T &&source, size_t uiCount)
template<typename T >
PL_ALWAYS_INLINE void	Prepend (T *pDestination, const T *pSource, size_t uiSourceCount, size_t uiCount)
template<typename T >
PL_ALWAYS_INLINE bool	IsEqual (const T *a, const T *b, size_t uiCount)
template<typename T >
PL_ALWAYS_INLINE void	ZeroFill (T *pDestination, size_t uiCount)
template<typename T , size_t N>
PL_ALWAYS_INLINE void	ZeroFillArray (T(&destination)[N])
template<typename T >
PL_ALWAYS_INLINE void	PatternFill (T *pDestination, plUInt8 uiBytePattern, size_t uiCount)
template<typename T , size_t N>
PL_ALWAYS_INLINE void	PatternFillArray (T(&destination)[N], plUInt8 uiBytePattern)
template<typename T >
PL_ALWAYS_INLINE plInt32	Compare (const T *a, const T *b, size_t uiCount)
template<typename T >
PL_ALWAYS_INLINE T *	AddByteOffset (T *pPtr, std::ptrdiff_t offset)
template<typename T >
PL_ALWAYS_INLINE T *	AlignBackwards (T *pPtr, size_t uiAlignment)
template<typename T >
PL_ALWAYS_INLINE T *	AlignForwards (T *pPtr, size_t uiAlignment)
template<typename T >
PL_ALWAYS_INLINE T	AlignSize (T uiSize, T uiAlignment)
template<typename T >
PL_ALWAYS_INLINE bool	IsAligned (const T *pPtr, size_t uiAlignment)
template<typename T >
PL_ALWAYS_INLINE bool	IsSizeAligned (T uiSize, T uiAlignment)

Static Public Member Functions
template<plConstructionMode mode, typename T >
static void	Construct (T *pDestination, size_t uiCount=1)
	Constructs uiCount objects of type T in a raw buffer at pDestination.
template<plConstructionMode mode, typename T >
static ConstructorFunction	MakeConstructorFunction ()
	Returns a function pointer to construct an instance of T. Returns nullptr for trivial types.
template<typename Destination , typename Source >
static void	CopyConstruct (Destination *pDestination, const Source &copy, size_t uiCount=1)
	Constructs uiCount objects of type T in a raw buffer at pDestination, by creating uiCount copies of copy.
template<typename T >
static void	CopyConstructArray (T *pDestination, const T *pSource, size_t uiCount)
	Constructs uiCount objects of type T in a raw buffer at pDestination from an existing array of objects at pSource by using copy construction.
template<typename T >
static CopyConstructorFunction	MakeCopyConstructorFunction ()
	Returns a function pointer to copy construct an instance of T.
template<typename T >
static void	MoveConstruct (T *pDestination, T &&source)
	Constructs an object of type T in a raw buffer at pDestination, by using move construction from source.
template<typename T >
static void	MoveConstruct (T *pDestination, T *pSource, size_t uiCount=1)
	Constructs uiCount objects of type T in a raw buffer at pDestination from an existing array of objects at pSource by using move construction.
template<typename Destination , typename Source >
static void	CopyOrMoveConstruct (Destination *pDestination, Source &&source)
	This function will either move call MoveConstruct or CopyConstruct for a single element source, depending on whether it was called with a rvalue reference or a const reference to source.
template<typename T >
static void	RelocateConstruct (T *pDestination, T *pSource, size_t uiCount=1)
	Constructs uiCount objects of type T in a raw buffer at pDestination from an existing array of objects at pSource by using move construction if availble, otherwise by copy construction. Calls destructor of source elements in any case (if it is a non primitive or mem-relocatable type).
template<typename T >
static void	Destruct (T *pDestination, size_t uiCount=1)
	Destructs uiCount objects of type T at pDestination.
template<typename T >
static DestructorFunction	MakeDestructorFunction ()
	Returns a function pointer to destruct an instance of T. Returns nullptr for POD-types.
template<typename T >
static void	Copy (T *pDestination, const T *pSource, size_t uiCount=1)
	Copies objects of type T from pSource to pDestination.
static void	RawByteCopy (void *pDestination, const void *pSource, size_t uiNumBytesToCopy)
	Copies exactly uiNumBytesToCopy from pSource to pDestination, independent of the involved types and their sizes.
template<typename T >
static void	CopyOverlapped (T *pDestination, const T *pSource, size_t uiCount=1)
	Copies objects of type T from pSource to pDestination.
template<typename T >
static void	Relocate (T *pDestination, T *pSource, size_t uiCount=1)
	Moves objects of type T from pSource to pDestination.
template<typename T >
static void	RelocateOverlapped (T *pDestination, T *pSource, size_t uiCount=1)
	Moves objects of type T from pSource to pDestination.
template<typename T >
static void	Prepend (T *pDestination, const T &source, size_t uiCount)
	Moves uiCount objects in pDestination by one object and copies source to the free space.
template<typename T >
static void	Prepend (T *pDestination, T &&source, size_t uiCount)
	Moves uiCount objects in pDestination by one object and moves source to the free space.
template<typename T >
static void	Prepend (T *pDestination, const T *pSource, size_t uiSourceCount, size_t uiCount)
	Moves uiCount objects in pDestination by uiSourceCount objects and copies source to the free space.
template<typename T >
static bool	IsEqual (const T *a, const T *b, size_t uiCount=1)
	Tests if objects of type T from pSource and pDestination are equal.
template<typename T >
static void	ZeroFill (T *pDestination, size_t uiCount=1)
	Zeros every byte in the provided memory buffer.
template<typename T , size_t N>
static void	ZeroFill (T(&destination)[N])=delete
	Overload to prevent confusing calling this on a single object or a static array of objects. Use ZeroFillArray() instead.
template<typename T , size_t N>
static void	ZeroFillArray (T(&destination)[N])
	Zeros every byte in the provided memory buffer.
template<typename T >
static void	PatternFill (T *pDestination, plUInt8 uiBytePattern, size_t uiCount=1)
	Fills every byte of the provided buffer with the given value.
template<typename T , size_t N>
static void	PatternFill (T(&destination)[N], plUInt8 uiBytePattern)=delete
	Overload to prevent confusing calling this on a single object or a static array of objects. Use PatternFillArray() instead.
template<typename T , size_t N>
static void	PatternFillArray (T(&destination)[N], plUInt8 uiBytePattern)
	Fills every byte of the provided buffer with the given value.
template<typename T >
static plInt32	Compare (const T *a, const T *b, size_t uiCount=1)
	Compares two buffers of raw memory byte wise.
static plInt32	RawByteCompare (const void *a, const void *b, size_t uiNumBytesToCompare)
	Compares exactly uiNumBytesToCompare from a and b, independent of the involved types and their sizes.
template<typename T >
static T *	AddByteOffset (T *pPtr, std::ptrdiff_t offset)
	Returns the address stored in ptr plus the given byte offset iOffset, cast to type T.
template<typename T >
static T *	AlignBackwards (T *pPtr, size_t uiAlignment)
	Aligns the pointer ptr by moving its address backwards to the previous multiple of uiAlignment.
template<typename T >
static T *	AlignForwards (T *pPtr, size_t uiAlignment)
	Aligns the pointer ptr by moving its address forwards to the next multiple of uiAlignment.
template<typename T >
static T	AlignSize (T uiSize, T uiAlignment)
	Aligns the given size uiSize by rounding up to the next multiple of the size.
template<typename T >
static bool	IsAligned (const T *pPtr, size_t uiAlignment)
	Checks whether ptr is aligned to a memory address that is a multiple of uiAlignment.
template<typename T >
static bool	IsSizeAligned (T uiSize, T uiAlignment)
	Checks whether the given size is aligned.
static void	ReserveLower4GBAddressSpace ()
	Reserves the lower 4GB of address space in 64-bit builds to ensure all allocations start above 4GB.

Detailed Description

This class provides functions to work on raw memory.

The following concepts are realized: Copy: Copying a object from a to b means that two equivalent objects will exists in both a and b. Move: Moving an object from a to b means that the object will exist in b afterwards but a will be empty afterwards, but not destructed. This strictly requires an available move constructor (compile error otherwise). Relocate: Relocating an object from a to b means that the object will exist in b afterwards but will no longer exist in a, which means a will be moved if available or copied, but destructed afterwards in any case. Construct: Constructing assumes that the destination does not contain a valid object. Overlapped: The source and destination range may overlap for the operation to be performed. The above mentioned concepts can be combined, e.g. RelocateConstruct for relocating to an uninitialized buffer.

Member Function Documentation

AddByteOffset()

template<typename T >

static T * plMemoryUtils::AddByteOffset ( T * pPtr, std::ptrdiff_t offset )

static

Returns the address stored in ptr plus the given byte offset iOffset, cast to type T.

This is useful when working with raw memory, to safely modify a pointer without having to take care of the details of pointer arithmetic.

Construct()

template<plConstructionMode mode, typename T >

static void plMemoryUtils::Construct ( T * pDestination, size_t uiCount = 1 )

static

Constructs uiCount objects of type T in a raw buffer at pDestination.

The plConstructionMode template argument determines whether trivial types will be skipped.

Copy()

template<typename T >

static void plMemoryUtils::Copy ( T * pDestination, const T * pSource, size_t uiCount = 1 )

static

Copies objects of type T from pSource to pDestination.

If the two buffers overlap use CopyOverlapped instead.

CopyOverlapped()

template<typename T >

static void plMemoryUtils::CopyOverlapped ( T * pDestination, const T * pSource, size_t uiCount = 1 )

static

Copies objects of type T from pSource to pDestination.

The two buffers may overlap when using this method.

RelocateOverlapped()

template<typename T >

static void plMemoryUtils::RelocateOverlapped ( T * pDestination, T * pSource, size_t uiCount = 1 )

static

Moves objects of type T from pSource to pDestination.

The two buffers may overlap when using this method.

ReserveLower4GBAddressSpace()

void plMemoryUtils::ReserveLower4GBAddressSpace ( )

static

Reserves the lower 4GB of address space in 64-bit builds to ensure all allocations start above 4GB.

Note

Note that this does NOT reserve 4GB of RAM, only address space. This can help to detect pointer truncation. In 32-bit builds it does nothing.

Currently only implemented on Windows.

---

The documentation for this class was generated from the following files:

• Code/Engine/Foundation/Memory/MemoryUtils.h
• Code/Engine/Foundation/Memory/Implementation/MemoryUtils.cpp
• Code/Engine/Foundation/Memory/Implementation/MemoryUtils_inl.h