OpenMPI  0.1.1
allocator_bucket_alloc.h
Go to the documentation of this file.
1 /**
2  * Copyright (c) 2004-2005 The Trustees of Indiana University and Indiana
3  * University Research and Technology
4  * Corporation. All rights reserved.
5  * Copyright (c) 2004-2005 The University of Tennessee and The University
6  * of Tennessee Research Foundation. All rights
7  * reserved.
8  * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
9  * University of Stuttgart. All rights reserved.
10  * Copyright (c) 2004-2005 The Regents of the University of California.
11  * All rights reserved.
12  * $COPYRIGHT$
13  *
14  * Additional copyrights may follow
15  *
16  * $HEADER$
17  */
18 
19 /** @file
20  * A generic memory bucket allocator.
21  **/
22 
23 #ifndef ALLOCATOR_BUCKET_ALLOC_H
24 #define ALLOCATOR_BUCKET_ALLOC_H
25 
26 #include "ompi_config.h"
27 #include <stdlib.h>
28 #include <string.h>
29 #include "opal/threads/mutex.h"
31 BEGIN_C_DECLS
32 
33 /**
34  * Structure for the header of each memory chunk
35  */
38  /**< The next chunk in the memory segment */
39  /**
40  * Union which holds either a pointer to the next free chunk
41  * or the bucket number. Based on the current location of the chunk
42  * we use one or the other of these fields. If the chunk is owned
43  * by the user, then the bucket field is set, which allow us to know
44  * in which specific bucket we have to put it back on free (as the
45  * chunk don't have the size attached). When the allocator own the
46  * chunk, the next_free fild is used, which allow us to put these
47  * chunks a list of free elements.
48  */
49  union u {
51  /**< if the chunk is free this will point to the next free chunk in the bucket */
52  int bucket; /**< the bucket number it belongs to */
53  } u; /**< the union */
54 };
55  /**
56  * Typedef so we don't have to use struct
57  */
59 
60 /**
61  * Structure that heads each segment
62  */
64  struct mca_allocator_bucket_chunk_header_t * first_chunk; /**< the first chunk of the header */
65  struct mca_allocator_bucket_segment_head_t * next_segment; /**< the next segment in the
66  bucket */
67 };
68 /**
69  * Typedef so we don't have to use struct
70  */
72 
73 /**
74  * Structure for each bucket
75  */
77  mca_allocator_bucket_chunk_header_t * free_chunk; /**< the first free chunk of memory */
78  opal_mutex_t lock; /**< the lock on the bucket */
79  mca_allocator_bucket_segment_head_t * segment_head; /**< the list of segment headers */
80 };
81 /**
82  * Typedef so we don't have to use struct
83  */
85 
86 /**
87  * Structure that holds the necessary information for each area of memory
88  */
90  mca_allocator_base_module_t super; /**< makes this a child of class mca_allocator_t */
91  mca_allocator_bucket_bucket_t * buckets; /**< the array of buckets */
92  int num_buckets; /**< the number of buckets */
94  /**< pointer to the function to get more memory */
96  /**< pointer to the function to free memory */
97 };
98 /**
99  * Typedef so we don't have to use struct
100  */
102 
103  /**
104  * Initializes the mca_allocator_bucket_options_t data structure for the passed
105  * parameters.
106  * @param mem a pointer to the mca_allocator_t struct to be filled in
107  * @param num_buckets The number of buckets the allocator will use
108  * @param get_mem_funct A pointer to the function that the allocator
109  * will use to get more memory
110  * @param free_mem_funct A pointer to the function that the allocator
111  * will use to free memory
112  *
113  * @retval Pointer to the initialized mca_allocator_bucket_options_t structure
114  * @retval NULL if there was an error
115  */
117  int num_buckets,
120 /**
121  * Accepts a request for memory in a specific region defined by the
122  * mca_allocator_bucket_options_t struct and returns a pointer to memory in that
123  * region or NULL if there was an error
124  *
125  * @param mem A pointer to the appropriate struct for the area of memory.
126  * @param size The size of the requested area of memory
127  *
128  * @retval Pointer to the area of memory if the allocation was successful
129  * @retval NULL if the allocation was unsuccessful
130  */
133  size_t size,
134  mca_mpool_base_registration_t** registration);
135 
136 /**
137  * Accepts a request for memory in a specific region defined by the
138  * mca_allocator_bucket_options_t struct and aligned by the specified amount and
139  * returns a pointer to memory in that region or NULL if there was an error
140  *
141  * @param mem A pointer to the appropriate struct for the area of
142  * memory.
143  * @param size The size of the requested area of memory
144  * @param alignment The requested alignment of the new area of memory. This
145  * MUST be a power of 2.
146  *
147  * @retval Pointer to the area of memory if the allocation was successful
148  * @retval NULL if the allocation was unsuccessful
149  *
150  */
153  size_t size,
154  size_t alignment,
155  mca_mpool_base_registration_t** registration);
156 
157 /**
158  * Attempts to resize the passed region of memory into a larger or a smaller
159  * region. If it is unsuccessful, it will return NULL and the passed area of
160  * memory will be untouched.
161  *
162  * @param mem A pointer to the appropriate struct for the area of
163  * memory.
164  * @param size The size of the requested area of memory
165  * @param ptr A pointer to the region of memory to be resized
166  *
167  * @retval Pointer to the area of memory if the reallocation was successful
168  * @retval NULL if the allocation was unsuccessful
169  *
170  */
173  void * ptr,
174  size_t size,
175  mca_mpool_base_registration_t** registration);
176 
177 /**
178  * Frees the passed region of memory
179  *
180  * @param mem A pointer to the appropriate struct for the area of
181  * memory.
182  * @param ptr A pointer to the region of memory to be freed
183  *
184  * @retval None
185  *
186  */
188  void * ptr);
189 
190 /**
191  * Frees all the memory from all the buckets back to the system. Note that
192  * this function only frees memory that was previously freed with
193  * mca_allocator_bucket_free().
194  *
195  * @param mem A pointer to the appropriate struct for the area of
196  * memory.
197  *
198  * @retval None
199  *
200  */
202 
203 /**
204  * Cleanup all resources held by this allocator.
205  *
206  * @param mem A pointer to the appropriate struct for the area of
207  * memory.
208  *
209  * @retval None
210  *
211  */
213 
214 OMPI_DECLSPEC extern mca_allocator_base_component_t mca_allocator_bucket_component;
215 
216 END_C_DECLS
217 
218 #endif /* ALLOCATOR_BUCKET_ALLOC_H */
int num_buckets
the number of buckets
Definition: allocator_bucket_alloc.h:92
int mca_allocator_bucket_cleanup(mca_allocator_base_module_t *mem)
Frees all the memory from all the buckets back to the system.
Definition: allocator_bucket_alloc.c:298
Structure for the header of each memory chunk.
Definition: allocator_bucket_alloc.h:36
mca_allocator_bucket_t * mca_allocator_bucket_init(mca_allocator_base_module_t *mem, int num_buckets, mca_allocator_base_component_segment_alloc_fn_t get_mem_funct, mca_allocator_base_component_segment_free_fn_t free_mem_funct)
Initializes the mca_allocator_bucket_options_t data structure for the passed parameters.
Definition: allocator_bucket_alloc.c:38
int bucket
the bucket number it belongs to
Definition: allocator_bucket_alloc.h:52
mca_allocator_base_module_t super
makes this a child of class mca_allocator_t
Definition: allocator_bucket_alloc.h:90
mca_allocator_base_component_segment_free_fn_t free_mem_fn
pointer to the function to free memory
Definition: allocator_bucket_alloc.h:95
struct mca_allocator_bucket_chunk_header_t * next_in_segment
The next chunk in the memory segment.
Definition: allocator_bucket_alloc.h:37
Definition: mutex_unix.h:53
Structure that heads each segment.
Definition: allocator_bucket_alloc.h:63
Definition: mpool.h:44
mca_allocator_bucket_bucket_t * buckets
the array of buckets
Definition: allocator_bucket_alloc.h:91
mca_allocator_base_component_segment_alloc_fn_t get_mem_fn
pointer to the function to get more memory
Definition: allocator_bucket_alloc.h:93
int mca_allocator_bucket_finalize(mca_allocator_base_module_t *mem)
Cleanup all resources held by this allocator.
Definition: allocator_bucket.c:47
void(* mca_allocator_base_component_segment_free_fn_t)(struct mca_mpool_base_module_t *module, void *segment)
A function to free memory from the control of the allocator framework back to the system...
Definition: allocator.h:113
Structure for each bucket.
Definition: allocator_bucket_alloc.h:76
struct mca_allocator_bucket_chunk_header_t * first_chunk
the first chunk of the header
Definition: allocator_bucket_alloc.h:64
void * mca_allocator_bucket_alloc(mca_allocator_base_module_t *mem, size_t size, mca_mpool_base_registration_t **registration)
Accepts a request for memory in a specific region defined by the mca_allocator_bucket_options_t struc...
Definition: allocator_bucket_alloc.c:74
void *(* mca_allocator_base_component_segment_alloc_fn_t)(struct mca_mpool_base_module_t *module, size_t *size, mca_mpool_base_registration_t **registration)
A function to get more memory from the system.
Definition: allocator.h:103
struct mca_allocator_bucket_chunk_header_t * next_free
if the chunk is free this will point to the next free chunk in the bucket
Definition: allocator_bucket_alloc.h:50
void * mca_allocator_bucket_alloc_align(mca_allocator_base_module_t *mem, size_t size, size_t alignment, mca_mpool_base_registration_t **registration)
Accepts a request for memory in a specific region defined by the mca_allocator_bucket_options_t struc...
Definition: allocator_bucket_alloc.c:156
mca_allocator_bucket_chunk_header_t * free_chunk
the first free chunk of memory
Definition: allocator_bucket_alloc.h:77
The data structure provided by each component to the framework which describes the component...
Definition: allocator.h:133
union mca_allocator_bucket_chunk_header_t::u u
the union
mca_allocator_bucket_segment_head_t * segment_head
the list of segment headers
Definition: allocator_bucket_alloc.h:79
struct mca_allocator_bucket_segment_head_t * next_segment
the next segment in the bucket
Definition: allocator_bucket_alloc.h:65
Union which holds either a pointer to the next free chunk or the bucket number.
Definition: allocator_bucket_alloc.h:49
Copyright (c) 2004-2005 The Trustees of Indiana University and Indiana University Research and Techno...
void * mca_allocator_bucket_realloc(mca_allocator_base_module_t *mem, void *ptr, size_t size, mca_mpool_base_registration_t **registration)
Attempts to resize the passed region of memory into a larger or a smaller region. ...
Definition: allocator_bucket_alloc.c:239
void mca_allocator_bucket_free(mca_allocator_base_module_t *mem, void *ptr)
Frees the passed region of memory.
Definition: allocator_bucket_alloc.c:281
Structure that holds the necessary information for each area of memory.
Definition: allocator_bucket_alloc.h:89
opal_mutex_t lock
the lock on the bucket
Definition: allocator_bucket_alloc.h:78
Mutual exclusion functions.
The data structure for each component.
Definition: allocator.h:78