Memory Reference

File
XSFoundation/include/XS/Functions/Memory.h
Author
Jean-David Gadina - www.xs-labs.com
Copyright
© (c) 2020 - Jean-David Gadina - www.xs-labs.com
Date
Sunday, September 27, 2020
Includes

Overview

Memory allocation functions

Tasks

XSAllocWithInfos

Allocates memory

XS_EXPORT void * XSAllocWithInfos( size_t bytes, XSClassID classID, const char *file, int line, const char *func );

Discussion

Do not use this function directly. Use the XSAlloc macro instead.

Parameters
  • bytes
    The number of bytes to allocate
  • classID
    The class ID, if any
  • file
    The file in which the allocation occurs
  • line
    The line number of the file in which the allocation occurs
  • func
    The function in which the allocation occurs
Return value

The allocated memory, or NULL

XSAutoAllocWithInfos

Allocates memory which will be automatically released

XS_EXPORT XS_AUTORELEASED void * XSAutoAllocWithInfos( size_t bytes, XSClassID classID, const char *file, int line, const char *func );

Discussion

Do not use this function directly. Use the XSAutoAlloc macro instead.

Parameters
  • bytes
    The number of bytes to allocate
  • classID
    The class ID, if any
  • file
    The file in which the allocation occurs
  • line
    The line number of the file in which the allocation occurs
  • func
    The function in which the allocation occurs
Return value

The allocated memory, or NULL

XSAutorelease

Auto-releases memory data

XS_EXPORT void * XSAutorelease( const void *memory );

Discussion

The memory data will be placed in the instance of the current auto-release pool, and will be released the next time the auto-release pool is drained.

Parameters
  • memory
    The memory data to release
Return value

The memory data

XSCopy

Copies a memory data object

XS_EXPORT void * XSCopyWithInfos( const void *memory, const char *file, int line, const char *func );

Discussion

Do not use this function directly. Use the XSCopy macro instead.

Parameters
  • memory
    The memory data object to copy
  • file
    The file in which the copy occurs
  • line
    The line number of the file in which the copy occurs
  • func
    The function in which the copy occurs
Return value

The copy of the memory data object

XSCopyWithInfos

Copies a memory data object

XS_EXPORT void * XSCopyWithInfos( const void *memory, const char *file, int line, const char *func );

Discussion

Do not use this function directly. Use the XSCopy macro instead.

Parameters
  • memory
    The memory data object to copy
  • file
    The file in which the copy occurs
  • line
    The line number of the file in which the copy occurs
  • func
    The function in which the copy occurs
Return value

The copy of the memory data object

XSEquals

Checks whether two memory data objects are equals

XS_EXPORT bool XSEquals( const void *memory1, const void *memory2 );

Parameters
  • memory1
    The first memory data object to compare
  • memory2
    The second memory data object to compare
Return value

True if both memory data objects are equals, otherwise false

XSGetRetainCount

Get the retain count of a memory data object

XS_EXPORT int64_t XSGetRetainCount( const void *memory );

Discussion

This functions is exposed for unit-tests and debug purposes. Never use it or rely on it in production code.

Parameters
  • memory
    The memory data object
Return value

The object's retain count

XSReallocWithInfos

Reallocates memory

XS_EXPORT void * XSReallocWithInfos( const void *memory, size_t bytes, const char *file, int line, const char *func );

Discussion

Do not use this function directly. Use the XSRealloc macro instead.

Parameters
  • memory
    The memory data to reallocate
  • bytes
    The number of bytes to reallocate
  • file
    The file in which the reallocation occurs
  • line
    The line number of the file in which the reallocation occurs
  • func
    The function in which the reallocation occurs
Return value

The reallocated memory, or NULL

XSReleaseWithInfos

Releases memory data

XS_EXPORT void XSReleaseWithInfos( const void *memory, const char *file, int line, const char *func );

Discussion

Do not use this function directly. Use the XSRelease macro instead.

Parameters
  • memory
    The memory data to release
  • file
    The file in which the release occurs
  • line
    The line number of the file in which the release occurs
  • func
    The function in which the release occurs

XSRetain

Retains memory data

XS_EXPORT void * XSRetainWithInfos( const void *memory, const char *file, int line, const char *func );

Discussion

Do not use this function directly. Use the XSRelease macro instead.

Parameters
  • memory
    The memory data to retain
  • file
    The file in which the retain occurs
  • line
    The line number of the file in which the retain occurs
  • func
    The function in which the retain occurs
Return value

The memory data

XSRetainWithInfos

Retains memory data

XS_EXPORT void * XSRetainWithInfos( const void *memory, const char *file, int line, const char *func );

Discussion

Do not use this function directly. Use the XSRelease macro instead.

Parameters
  • memory
    The memory data to retain
  • file
    The file in which the retain occurs
  • line
    The line number of the file in which the retain occurs
  • func
    The function in which the retain occurs
Return value

The memory data

Macros

XSAlloc

Allocates memory

#ifdef DEBUG #define XSAlloc( _bytes_ ) XSAllocWithInfos( _bytes_, 0, __FILE__, __LINE__, __func__ ) #else #define XSAlloc( _bytes_ ) XSAllocWithInfos( _bytes_, 0, NULL, 0, NULL ) #endif

Discussion

The allocated memory will be zero-filled

Parameters
  • _bytes_
    The number of bytes to allocate
Return value

The allocated memory, or NULL

XSAutoAlloc

Allocates memory which will be automatically released

#ifdef DEBUG #define XSAutoAlloc( _bytes_ ) XSAutoAllocWithInfos( _bytes_, 0, __FILE__, __LINE__, __func__ ) #else #define XSAutoAlloc( _bytes_ ) XSAutoAllocWithInfos( _bytes_, 0, NULL, 0, NULL ) #endif

Discussion

The memory data will be placed in the instance of the current auto-release pool, and will be released the next time the auto-release pool is drained. The allocated memory will be zero-filled

Parameters
  • _bytes_
    The number of bytes to allocate
Return value

The allocated memory, or NULL

XSBadAlloc

Issues a fatal error message for a bad memory allocation

#define XSBadAlloc() XSFatalError( "Cannot allocate memory" )

XSCopy

Copies a memory data object

#ifdef DEBUG #define XSCopy( _memory_ ) XSCopyWithInfos( _memory_, __FILE__, __LINE__, __func__ ) #else #define XSCopy( _memory_ ) XSCopyWithInfos( _memory_, NULL, 0, NULL ) #endif

Parameters
  • _memory_
    The memory data object to copy
Return value

The copy of the memory data object

XSRealloc

Reallocates memory

#ifdef DEBUG #define XSRealloc( _memory_, _bytes_ ) XSReallocWithInfos( _memory_, _bytes_, __FILE__, __LINE__, __func__ ) #else #define XSRealloc( _memory_, _bytes_ ) XSReallocWithInfos( _memory_, _bytes_, NULL, 0, NULL ) #endif

Discussion

If the requested bytes are larger than the previous allocation size, additional data will be zero-filled.

Parameters
  • _memory_
    The memory data to reallocate
  • _bytes_
    The number of bytes to reallocate
Return value

The reallocated memory, or NULL

XSRelease

Releases memory data

#ifdef DEBUG #define XSRelease( _memory_ ) XSReleaseWithInfos( _memory_, __FILE__, __LINE__, __func__ ) #else #define XSRelease( _memory_ ) XSReleaseWithInfos( _memory_, NULL, 0, NULL ) #endif

Discussion

Memory may be freed if the retain count for the memory data reaches 0.

Parameters
  • _memory_
    The memory data to release

XSRetain

Retains memory data

#ifdef DEBUG #define XSRetain( _memory_ ) XSRetainWithInfos( _memory_, __FILE__, __LINE__, __func__ ) #else #define XSRetain( _memory_ ) XSRetainWithInfos( _memory_, NULL, 0, NULL ) #endif

Parameters
  • _memory_
    The memory data to retain
Return value

The memory data