/
garbage.h
112 lines (98 loc) · 3.63 KB
/
garbage.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
/** @file garbage.h Garbage collector. @ingroup core
*
* Stores pointers to unnecessary areas of memory and frees them later. Garbage
* collection must be requested manually, e.g., at the end of the frame once
* per second. Garbage is also thread-specific; recycling must be done
* separately in each thread.
*
* @authors Copyright © 2012-2014 Jaakko Keränen <jaakko.keranen@iki.fi>
*
* @par License
* LGPL: http://www.gnu.org/licenses/lgpl.html
*
* <small>This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU Lesser General Public License as published by
* the Free Software Foundation; either version 3 of the License, or (at your
* option) any later version. This program is distributed in the hope that it
* will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
* of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
* General Public License for more details. You should have received a copy of
* the GNU Lesser General Public License along with this program; if not, see:
* http://www.gnu.org/licenses</small>
*/
#ifndef LIBDENG2_GARBAGE_COLLECTOR_H
#define LIBDENG2_GARBAGE_COLLECTOR_H
#include "../libdeng2.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* Puts a region of allocated memory up for garbage collection in the current
* thread. The memory will be available for use until Garbage_Recycle() is
* called.
*
* @param ptr Pointer to memory allocated with malloc().
*/
DENG2_PUBLIC void Garbage_TrashMalloc(void *ptr);
/**
* Pointer to an instance destructor;
*/
typedef void (*GarbageDestructor)(void *);
/**
* Puts an object up for garbage collection in the current thread. The object
* will be available for use until Garbage_Recycle() is called in the thread.
*
* @param ptr Pointer to the object.
* @param destructor Function that destroys the object.
*/
DENG2_PUBLIC void Garbage_TrashInstance(void *ptr, GarbageDestructor destructor);
/**
* Determines whether a memory pointer has been trashed. Only the current
* thread's collector is searched.
*
* @param ptr Pointer to memory.
*
* @return @c true if the pointer is in the trash.
*/
DENG2_PUBLIC int Garbage_IsTrashed(void const *ptr);
/**
* Removes a region from the current thread's collector, if it is still there.
* @warning Do not call this if there is a chance that the pointer has already
* been freed.
*
* @param ptr Pointer to memory previously put in the trash.
*/
DENG2_PUBLIC void Garbage_Untrash(void *ptr);
/**
* Removes a pointer from the garbage. This needs to be called if the
* previously trashed memory was manually freed.
*
* @param ptr Pointer to memory.
*/
DENG2_PUBLIC void Garbage_RemoveIfTrashed(void *ptr);
/**
* Frees all pointers given over to the current thread's garbage collector.
* Every thread that uses garbage collection must call this periodically
* or the trashed memory will not be freed.
*/
DENG2_PUBLIC void Garbage_Recycle(void);
/**
* Frees all pointers in every thread's garbage if they are using a specific
* destructor function.
*
* @param destructor Destructor function.
*/
DENG2_PUBLIC void Garbage_RecycleAllWithDestructor(GarbageDestructor destructor);
/**
* Recycles all garbage of the current thread and deletes the thread's garbage
* collector. Should be called right before the thread ends.
*
* This differs from Garbage_Recycle() in that all the thread-specific internal
* resources are freed, not just the thread's trashed memory. The thread can
* safely end after this.
*/
DENG2_PUBLIC void Garbage_ClearForThread(void);
#ifdef __cplusplus
} // extern "C"
#endif
#endif // LIBDENG2_GARBAGE_COLLECTOR_H