merge from 23153 to 23595
[blender.git] / doc / blender-guardedalloc.txt
1 MEMORY MANAGEMENT IN BLENDER (guardedalloc)
2 -------------------------------------------
3
4 NOTE: This file does not cover memutil and smart pointers and rerefence counted
5       garbage collection, which are contained in the memutil module.
6
7 Blender takes care of dynamic memory allocation using a set of own functions
8 which are recognizeable through their MEM_ prefix. All memory allocation and
9 deallocation in blender is done through these functions.
10
11 The following functions are available through MEM_guardedalloc.h:
12
13 For normal operation:
14 ---------------------
15
16 void *MEM_[mc]allocN(unsigned int len, char * str);
17
18 - nearest ANSI counterpart: malloc()
19 - str must be a static string describing the memory block (used for debugging
20 memory management problems)
21 - returns a memory block of length len
22 - MEM_callocN clears the memory block to 0
23
24 void *MEM_dupallocN(void *vmemh);
25
26 - nearest ANSI counterpart: combination malloc() and memcpy()
27 - returns a pointer to a copy of the given memory area
28
29 short MEM_freeN(void *vmemh);
30
31 - nearest ANSI counterpart: free()
32 - frees the memory area given by the pointer
33 - returns 0 on success and !=0 on error
34
35 int MEM_allocN_len(void *vmemh);
36
37 - nearest ANSI counterpart: none known
38 - returns the length of the given memory area
39
40 For debugging:
41 --------------
42
43 void MEM_set_error_stream(FILE*);
44
45 - this sets the file the memory manager should use to output debugging messages
46 - if the parameter is NULL the messages are suppressed
47 - default is that messages are suppressed
48
49 void MEM_printmemlist(void);
50
51 - if err_stream is set by MEM_set_error_stream() this function dumps a list of all
52 currently allocated memory blocks with length and name to the stream
53
54 int MEM_check_memory_integrity(void);
55
56 - this function tests if the internal structures of the memory manager are intact
57 - returns 0 on success and !=0 on error