User:Monster Iestyn/Source Code Documentation/z_zone.h
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 |
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_t s, 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
| |
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. |