User:Monster Iestyn/Source Code Documentation/z_zone.h

From SRB2 Wiki
Jump to navigation Jump to search
Online link GitHub entry
File type C header file
#include guard __Z_ZONE__

This header file contains macros and function prototypes for SRB2's zone memory system. Under this system, allocated memory blocks are added to a linked list, so that the game can keep track of them, purge them if necessary, and calculate how much memory is in use.

Includes

Attribute macros

GCC-specific macros

Macro Defined as Description
FUNCALLOC(X) 
__attribute__((alloc_size(X)))
(GCC 2.4.5 and above only)

Used on functions that return a pointer and take at least one argument of integer or enum type. This indicates that the returned pointer points to memory whose size is given by the function argument at position X (i.e.: a value of 1 is the first argument, 2 is the second, etc). This allows the compiler to to improve the results of __builtin_object_size, a function for returning the size of an object.

Purge tag macros

These tags are assigned to blocks of allocated memory by Z_Malloc, Z_Calloc etc so that, later, all memory of a given tag can be purged via Z_FreeTags.

Other notes on purging behavior:

  • Tags < PU_LEVEL are not purged until freed explicitly.
  • Tags s.t. PU_LEVEL <= tag < PU_PURGELEVEL are purged at level start.
  • Tags >= PU_PURGELEVEL are purgable whenever needed.
Value Name Description
1 PU_STATIC Static entire execution time.
2 PU_LUA Static entire execution time. Used by Lua so it doesn't get caught in loops forever.
11 PU_SOUND Static while playing, for sounds.
12 PU_MUSIC Static while playing, for music.
13 PU_HUDGFX Static until WAD added.
21 PU_HWRPATCHINFO Hardware GLPatch_t struct for OpenGL texture cache.
22 PU_HWRPATCHCOLMIPMAP Hardware GLMipmap_t struct colormap variation of patch.
48 PU_HWRCACHE Static until unlocked, for hardware renderer.
49 PU_CACHE Static until unlocked.
50 PU_LEVEL Static until level exited.
51 PU_LEVSPEC A special thinker in a level.
52 PU_HWRPLANE If ZPLANALLOC is enabled in hw_bsp.c, this is used to alloc polygons for OpenGL.
100 PU_PURGELEVEL Purgeable whenever needed. (Never actually used as a tag for memory blocks)
101 PU_CACHE_UNLOCKED "Unlocked" cached memory
102 PU_HWRCACHE_UNLOCKED "Unlocked" PU_HWRCACHE memory
103 PU_HWRPATCHINFO_UNLOCKED "Unlocked" PU_HWRPATCHINFO memory

Functions

Note that if the macros ZDEBUG or PARANOIA are defined, some of the functions listed below may be instead defined as function macros for an auxillary set of functions that allow them to get the file and line in the source code the functions were called from. These file and line may then be printed in crash or debugging messages.

Function prototypes

Function name Return type Params Defined in Attributes Description
Zone memory initialisation
Z_Init void none z_zone.c Initialises zone memory. Used at game startup.
Zone memory allocation – ZDEBUG defined
Z_Free2 void void *ptr,
const char *file,
INT32 line 		z_zone.c Frees allocated memory. file and line are the source code file and line number the function was called from, which will be printed in zone memory-related I_Error messages.
Z_Malloc2 void * size_t size,
INT32 tag,
void *user,
INT32 alignbits,
const char *file,
INT32 line 		z_zone.c FUNCALLOC(1) Allocates a block of memory. file and line are the source code file and line number the function was called from, which will be printed in zone memory-related I_Error messages.
Z_Calloc2 void * size_t size,
INT32 tag,
void *user,
INT32 alignbits,
const char *file,
INT32 line 		z_zone.c FUNCALLOC(1) Allocates a block of memory, and initialises its bytes to zero. file and line are the source code file and line number the function was called from, which will be printed in zone memory-related I_Error messages.
Z_Realloc2 void * void *ptr,
size_t size,
INT32 tag,
void *user,
INT32 alignbits,
const char *file,
INT32 line 		z_zone.c FUNCALLOC(2) Reallocates a block of memory with a new size. file and line are the source code file and line number the function was called from, which will be printed in zone memory-related I_Error messages.
Zone memory allocation – ZDEBUG not defined
Z_Free void void *ptr z_zone.c Frees allocated memory.
Z_MallocAlign void * size_t size,
INT32 tag,
void *user,
INT32 alignbits 		z_zone.c FUNCALLOC(1) Allocates a block of memory with a set alignment.
Z_CallocAlign void * size_t size,
INT32 tag,
void *user,
INT32 alignbits 		z_zone.c FUNCALLOC(1) Allocates a block of memory with a set alignment, and initialises its bytes to zero.
Z_ReallocAlign void * void *ptr,
size_t size,
INT32 tag,
void *user,
INT32 alignbits 		z_zone.c FUNCALLOC(2) Reallocates a block of memory with a new size and alignment.
Zone memory allocation – Other
Z_FreeTags void INT32 lowtag,
INT32 hightag 		z_zone.c Frees all memory for a given set of tags.
Utility functions
Z_CheckMemCleanup void none z_zone.c Frees memory blocks with purge tags >= PU_PURGELEVEL after a set number of calls of this function.
Z_CheckHeap void INT32 i z_zone.c Checks the heap, as well as the memhdr_ts, for any corruption or other problems. i is a number used to identify from where in the code Z_CheckHeap was called.

As of the current release of SRB2, there are only four i values used. Given below are the functions that call Z_CheckHeap with each of these values:

  • -2: G_DoLoadLevel (only if PARANOIA is defined)
  • -1: Command_Memfree_f
  • 420: Z_FreeTags
  • 9875: Command_GrStats_f
Zone memory modification – PARANOIA defined
Z_ChangeTag2 void void *ptr,
INT32 tag,
const char *file,
INT32 line 		z_zone.c Changes a memory block's purge tag. file and line are the source code file and line number the function was called from, which will be printed in zone memory-related I_Error messages.
Z_SetUser2 void void *ptr,
void **newuser,
const char *file,
INT32 line 		z_zone.c Changes a memory block's user. file and line are the source code file and line number the function was called from, which will be printed in zone memory-related I_Error messages.
Zone memory modification – PARANOIA not defined
Z_ChangeTag void void *ptr,
INT32 tag 		z_zone.c Changes a memory block's purge tag.
Z_SetUser void void *ptr,
void **newuser 		z_zone.c Changes a memory block's user.
Zone memory usage
Z_TagUsage size_t INT32 tagnum z_zone.c Calculates memory usage for a given tag.
Z_TagsUsage size_t INT32 lowtag,
INT32 hightag 		z_zone.c Calculates memory usage for a given set of tags.
Miscellaneous
Z_StrDup char * const char *in z_zone.c Creates a copy of a string.

Function macros

Macro Defined as Description
Zone memory allocation – ZDEBUG defined
Z_Free(p) 
Z_Free2(p, __FILE__, __LINE__)
Frees allocated memory.
Z_MallocAlign(s,t,u,a) 
Z_Malloc2(s, t, u, a, __FILE__, __LINE__)
Allocates a block of memory with a set alignment.
Z_CallocAlign(s,t,u,a) 
Z_Calloc2(s, t, u, a, __FILE__, __LINE__)
Allocates a block of memory with a set alignment, and initialises its bytes to zero.
Z_ReallocAlign(s,t,u,a) 
Z_Realloc2(p,s, t, u, a, __FILE__, __LINE__)
Reallocates a block of memory with a new size and alignment.
Zone memory allocation – Other
Z_Malloc(s,t,u) 
Z_MallocAlign(s, t, u, 0)
Allocates a block of memory.
Z_Calloc(s,t,u) 
Z_CallocAlign(s, t, u, 0)
Allocates a block of memory, and initialises its bytes to zero.
Z_Realloc(p,s,t,u) 
Z_ReallocAlign(p, s, t, u, 0)
Reallocates a block of memory with a new size.
Z_FreeTag(tagnum) 
Z_FreeTags(tagnum, tagnum)
Frees all memory for a given tag.
Zone memory modification – PARANOIA defined
Z_ChangeTag(p,t) 
Z_ChangeTag2(p, t, __FILE__, __LINE__)
Changes a memory block's purge tag.
Z_SetUser(p,u) 
Z_SetUser2(p, u, __FILE__, __LINE__)
Changes a memory block's user.
Zone memory modification – PARANOIA not defined
Z_ChangeTag(p,t) 
Z_ChangeTag2(p, t)
Changes a memory block's purge tag.
Z_SetUser(p,u) 
Z_SetUser2(p, u)
Changes a memory block's user.
Miscellaneous
Z_Unlock(p) 
(void)p
The NDS port of SRB2 formerly used this to "unlocks" cached memory. This has no effect as of v2.2.
Retrieved from "https://wiki.srb2.org/w/index.php?title=User:Monster_Iestyn/Source_Code_Documentation/z_zone.h&oldid=114538"