1 #ifndef __FT_SYSTEM_MEMORY_H__
2 #define __FT_SYSTEM_MEMORY_H__
3 
4 #include <ft2build.h>
5 
6 FT_BEGIN_HEADER
7 
8  /************************************************************************/
9  /************************************************************************/
10  /*****                                                              *****/
11  /*****    NOTE: THE CONTENT OF THIS FILE IS NOT CURRENTLY USED      *****/
12  /*****          IN NORMAL BUILDS.  CONSIDER IT EXPERIMENTAL.        *****/
13  /*****                                                              *****/
14  /************************************************************************/
15  /************************************************************************/
16 
17 
18  /*@**********************************************************************
19   *
20   * @type: FT_Memory
21   *
22   * @description:
23   *   opaque handle to a memory manager handle. Note that since FreeType
24   *   2.2, the memory manager structure FT_MemoryRec is hidden to client
25   *   applications.
26   *
27   *   however, you can still define custom allocators easily using the
28   *   @ft_memory_new API
29   */
30   typedef struct FT_MemoryRec_*   FT_Memory;
31 
32 
33  /*@**********************************************************************
34   *
35   * @functype: FT_Memory_AllocFunc
36   *
37   * @description:
38   *   a function used to allocate a block of memory.
39   *
40   * @input:
41   *   size     :: size of blocks in bytes. Always > 0 !!
42   *   mem_data :: memory-manager specific optional argument
43   *               (see @ft_memory_new)
44   *
45   * @return:
46   *   address of new block. NULL in case of memory exhaustion
47   */
48   typedef FT_Pointer  (*FT_Memory_AllocFunc)( FT_ULong   size,
49                                               FT_Pointer mem_data );
50 
51 
52  /*@**********************************************************************
53   *
54   * @functype: FT_Memory_FreeFunc
55   *
56   * @description:
57   *   a function used to release a block of memory created through
58   *   @FT_Memory_AllocFunc or @FT_Memory_ReallocFunc
59   *
60   * @input:
61   *   block    :: address of target memory block. cannot be NULL !!
62   *   mem_data :: memory-manager specific optional argument
63   *               (see @ft_memory_new)
64   */
65   typedef void        (*FT_Memory_FreeFunc) ( FT_Pointer  block,
66                                               FT_Pointer  mem_data );
67 
68 
69  /*@**********************************************************************
70   *
71   * @functype: FT_Memory_ReallocFunc
72   *
73   * @description:
74   *   a function used to reallocate a memory block.
75   *
76   * @input:
77   *   block    :: address of target memory block. cannot be NULL !!
78   *   new_size :: new requested size in bytes
79   *   cur_size :: current block size in bytes
80   *   mem_data :: memory-manager specific optional argument
81   *               (see @ft_memory_new)
82   */
83   typedef FT_Pointer  (*FT_Memory_ReallocFunc)( FT_Pointer   block,
84                                                 FT_ULong     new_size,
85                                                 FT_ULong     cur_size,
86                                                 FT_Pointer   mem_data );
87 
88 
89  /*@**********************************************************************
90   *
91   * @functype: FT_Memory_CreateFunc
92   *
93   * @description:
94   *   a function used to create a @FT_Memory object to model a
95   *   memory manager
96   *
97   * @input:
98   *   size      :: size of memory manager structure in bytes
99   *   init_data :: optional initialisation argument
100   *
101   * @output:
102   *   amem_data :: memory-manager specific argument to block management
103   *                routines.
104   *
105   * @return:
106   *   handle to new memory manager object. NULL in case of failure
107   */
108   typedef FT_Pointer  (*FT_Memory_CreateFunc)( FT_UInt     size,
109                                                FT_Pointer  init_data,
110                                                FT_Pointer *amem_data );
111 
112 
113  /*@**********************************************************************
114   *
115   * @functype: FT_Memory_DestroyFunc
116   *
117   * @description:
118   *   a function used to destroy a given @FT_Memory manager
119   *
120   * @input:
121   *   memory   :: target memory manager handle
122   *   mem_data :: option manager-specific argument
123   */
124   typedef void        (*FT_Memory_DestroyFunc)( FT_Memory  memory,
125                                                 FT_Pointer mem_data );
126 
127 
128  /*@**********************************************************************
129   *
130   * @struct: FT_Memory_FuncsRec
131   *
132   * @description:
133   *   a function used to hold all methods of a given memory manager
134   *   implementation.
135   *
136   * @fields:
137   *   mem_alloc   :: block allocation routine
138   *   mem_free    :: block release routine
139   *   mem_realloc :: block re-allocation routine
140   *   mem_create  :: manager creation routine
141   *   mem_destroy :: manager destruction routine
142   */
143   typedef struct FT_Memory_FuncsRec_
144   {
145     FT_Memory_AllocFunc     mem_alloc;
146     FT_Memory_FreeFunc      mem_free;
147     FT_Memory_ReallocFunc   mem_realloc;
148     FT_Memory_CreateFunc    mem_create;
149     FT_Memory_DestroyFunc   mem_destroy;
150 
151   } FT_Memory_FuncsRec, *FT_Memory_Funcs;
152 
153 
154  /*@**********************************************************************
155   *
156   * @type: FT_Memory_Funcs
157   *
158   * @description:
159   *   a pointer to a constant @FT_Memory_FuncsRec structure used to
160   *   describe a given memory manager implementation.
161   */
162   typedef const FT_Memory_FuncsRec*  FT_Memory_Funcs;
163 
164 
165  /*@**********************************************************************
166   *
167   * @function: ft_memory_new
168   *
169   * @description:
170   *   create a new memory manager, given a set of memory methods
171   *
172   * @input:
173   *   mem_funcs     :: handle to memory manager implementation descriptor
174   *   mem_init_data :: optional initialisation argument, passed to
175   *                    @FT_Memory_CreateFunc
176   *
177   * @return:
178   *   new memory manager handle. NULL in case of failure
179   */
180   FT_BASE( FT_Memory )
181   ft_memory_new( FT_Memory_Funcs  mem_funcs,
182                  FT_Pointer       mem_init_data );
183 
184 
185  /*@**********************************************************************
186   *
187   * @function: ft_memory_destroy
188   *
189   * @description:
190   *   destroy a given memory manager
191   *
192   * @input:
193   *   memory :: handle to target memory manager
194   */
195   FT_BASE( void )
196   ft_memory_destroy( FT_Memory  memory );
197 
198 /* */
199 
200 FT_END_HEADER
201 
202 #endif /* __FT_SYSTEM_MEMORY_H__ */
203