Point Cloud Library (PCL) 1.13.0
opennurbs_workspace.h
1/* $NoKeywords: $ */
2/*
3//
4// Copyright (c) 1993-2012 Robert McNeel & Associates. All rights reserved.
5// OpenNURBS, Rhinoceros, and Rhino3D are registered trademarks of Robert
6// McNeel & Associates.
7//
8// THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT EXPRESS OR IMPLIED WARRANTY.
9// ALL IMPLIED WARRANTIES OF FITNESS FOR ANY PARTICULAR PURPOSE AND OF
10// MERCHANTABILITY ARE HEREBY DISCLAIMED.
11//
12// For complete openNURBS copyright information see <http://www.opennurbs.org>.
13//
14////////////////////////////////////////////////////////////////
15*/
16
17#if !defined(OPENNURBS_WORKSPACE_INC_)
18#define OPENNURBS_WORKSPACE_INC_
19
20/*
21Description:
22 Use ON_Workspace classes on the stack to efficiently get
23 and automatically clean up workspace memory and scratch
24 files.
25*/
26class ON_CLASS ON_Workspace
27{
28public:
29 /*
30 Description:
31 ON_Workspace classes should be on the stack
32 or as members on classes that are never copied.
33 The destructor frees memory that was allocated by
34 ON_Workspace::GetMemory and closes files that were
35 opened with ON_Workspace::OpenFile.
36 */
38
39 /*
40 Description:
41 The destructor frees memory that was allocated by
42 ON_Workspace::GetMemory and closes files that were
43 opened with ON_Workspace::OpenFile.
44 */
46
47
48 /*
49 Description:
50 The destructor frees memory that was allocated by
51 ON_Workspace::GetMemory and closes files that were
52 opened with ON_Workspace::OpenFile. The workspace
53 can be used again after calling destroy.
54 */
55 void Destroy();
56
57 /*
58 Description:
59 Gets a block of heap memory that will be freed by
60 ~ON_Workspace. The intent of ON_Workspace::GetMemory
61 is to provide an easy way to get blocks of scratch
62 memory without having to worry about cleaning up
63 before returning.
64 Parameters:
65 sz - [in] (>0) size of memory block in bytes.
66 If sz <= 0, then NULL is returned.
67 Returns:
68 A pointer to the memory block.
69 Remarks.
70 onmalloc() is used to get the block of memory.
71 Do NOT free the pointer returned by GetMemory().
72 ~ON_Workspace() will free the memory. If you decide
73 you want to keep the memory block, pass the pointer
74 to KeepMemory before ~ON_Workspace is called.
75 See Also:
76 ON_Workspace::::~ON_Workspace
77 ON_Workspace::KeepMemory
78 ON_Workspace::GrowMemory
79 ON_Workspace::GetIntMemory
80 ON_Workspace::GetDoubleMemory
81 ON_Workspace::GetPointMemory
82 ON_Workspace::GetVectorMemory
83 */
84 void* GetMemory( std::size_t sz );
85
86 /*
87 Description:
88 Gets an array of integers that will be freed by ~ON_Workspace.
89 The intent of ON_Workspace::GetIntMemory is to provide
90 an easy way to get scratch integer arrays without
91 having to worry about cleaning up before returning.
92 Parameters:
93 count - [in] (>0) number of integers in memory block.
94 If count <= 0, then NULL is returned.
95 Returns:
96 A pointer to the array of integers.
97 Remarks.
98 This is a simple helper function so you don't have to
99 mess around with (int*) casts and sizeof(int)s in a call
100 to GetMemory(). It is exactly like calling
101 (int*)GetMemory(count*sizeof(int));
102 See Also:
103 ON_Workspace::GetMemory
104 ON_Workspace::KeepMemory
105 ON_Workspace::GrowIntMemory
106 */
107 int* GetIntMemory( std::size_t count );
108
109 /*
110 Description:
111 Gets an matrix of integers
112 Parameters:
113 row_count - [in] (>0) number of rows
114 col_count - [in] (>0) number of columns
115 Returns:
116 A pointer p so that p[i][j] is an integer when
117 0 <= i < row_count and 0 <= j < col_count.
118 Remarks.
119 This is a simple helper function so you don't have to
120 mess around building the 2d array.
121 See Also:
122 ON_Workspace::KeepMemory
123 */
124 int** GetIntMemory( std::size_t row_count, std::size_t col_count );
125
126 /*
127 Description:
128 Gets an array of doubles that will be freed by ~ON_Workspace.
129 The intent of ON_Workspace::GetDoubleMemory is to provide
130 an easy way to get scratch double arrays without
131 having to worry about cleaning up before returning.
132 Parameters:
133 count - [in] (>0) number of doubles in memory block.
134 If count <= 0, then NULL is returned.
135 Returns:
136 A pointer to the array of doubles.
137 Remarks.
138 This is a simple helper function so you don't have to
139 mess around with (double*) casts and sizeof(double)s
140 in a call to GetMemory(). It is exactly like calling
141 (double*)GetMemory(count*sizeof(double));
142 See Also:
143 ON_Workspace::GetMemory
144 ON_Workspace::KeepMemory
145 ON_Workspace::GrowIntMemory
146 */
147 double* GetDoubleMemory( std::size_t count );
148
149 /*
150 Description:
151 Gets an matrix of doubles
152 Parameters:
153 row_count - [in] (>0) number of rows
154 col_count - [in] (>0) number of columns
155 Returns:
156 A pointer p so that p[i][j] is an double when
157 0 <= i < row_count and 0 <= j < col_count.
158 Remarks.
159 This is a simple helper function so you don't have to
160 mess around building the 2d array.
161 See Also:
162 ON_Workspace::KeepMemory
163 */
164 double** GetDoubleMemory( std::size_t row_count, std::size_t col_count );
165
166 /*
167 Description:
168 Gets an array of ON_3dPoints that will be freed by ~ON_Workspace.
169 The intent of ON_Workspace::GetPointMemory is to
170 provide an easy way to get scratch point arrays without
171 having to worry about cleaning up before returning.
172 Parameters:
173 count - [in] (>0) number of points in memory block.
174 If count <= 0, then NULL is returned.
175 Returns:
176 A pointer to the memory block.
177 Remarks.
178 This is a simple helper function so you don't have to
179 mess around with (ON_3dPoint*) casts and sizeof(ON_3dPoint)s
180 in a call to GetMemory(). It is exactly like calling
181 (ON_3dPoint*)GetMemory(count*sizeof(ON_3dPoint));
182 See Also:
183 ON_Workspace::GetMemory
184 ON_Workspace::KeepMemory
185 ON_Workspace::GrowIntMemory
186 */
187 ON_3dPoint* GetPointMemory( std::size_t count );
188
189 /*
190 Description:
191 Gets an array of ON_3dVectors that will be freed by ~ON_Workspace.
192 The intent of ON_Workspace::GetVectorMemory is to
193 provide an easy way to get scratch Vector arrays without
194 having to worry about cleaning up before returning.
195 Parameters:
196 count - [in] (>0) number of Vectors in memory block.
197 If count <= 0, then NULL is returned.
198 Returns:
199 A pointer to the memory block.
200 Remarks.
201 This is a simple helper function so you don't have to
202 mess around with (ON_3dVector*) casts and sizeof(ON_3dVector)s
203 in a call to GetMemory(). It is exactly like calling
204 (ON_3dVector*)GetMemory(count*sizeof(ON_3dVector));
205 See Also:
206 ON_Workspace::GetMemory
207 ON_Workspace::KeepMemory
208 ON_Workspace::GrowIntMemory
209 */
210 ON_3dVector* GetVectorMemory( std::size_t count );
211
212 /*
213 Description:
214 Grows a block of heap memory that was allocated by
215 ON_Workspace::GetMemory.
216 Parameters:
217 ptr - [in] pointer returned by an earlier call to
218 GetMemory or GrowMemory.
219 sz - [in] (>0) size of memory block in bytes.
220 If sz <= 0, then NULL is returned.
221 If ptr is not NULL and was not allocated by an
222 earlier call to GetMemory or GrowMemory, then
223 NULL is returned.
224 Returns:
225 A pointer to the memory block.
226 Remarks.
227 onrealloc() is used to grow the block of memory.
228 Do NOT free the pointer returned by GrowMemory().
229 ~ON_Workspace() will free the memory. If you decide
230 you want to keep the memory block, pass the pointer
231 to KeepMemory before ~ON_Workspace is called.
232 See Also:
233 ON_Workspace::GetMemory
234 ON_Workspace::KeepMemory
235 ON_Workspace::GrowIntMemory
236 ON_Workspace::GrowDoubleMemory
237 ON_Workspace::GrowPointMemory
238 ON_Workspace::GrowVectorMemory
239 */
240 void* GrowMemory( void* ptr, std::size_t sz );
241
242 /*
243 Description:
244 Grows the array of integers that was allocated by
245 GetIntMemory or GrowIntMemory.
246 Parameters:
247 ptr - [in] pointer returned by an earlier call to
248 GetIntMemory or GrowIntMemory.
249 count - [in] (>0) number of integers in memory block.
250 If count <= 0, then NULL is returned.
251 If ptr was not allocated by this ON_Workspace
252 class, then NULL is returned.
253 Returns:
254 A pointer to the integer array.
255 Remarks.
256 onrealloc() is used to grow the block of memory.
257 Do NOT free the pointer returned by GrowIntMemory().
258 ~ON_Workspace() will free the memory. If you decide
259 you want to keep the memory block, pass the pointer
260 to KeepMemory before ~ON_Workspace is called.
261 See Also:
262 ON_Workspace::GetIntMemory
263 ON_Workspace::KeepMemory
264 */
265 int* GrowIntMemory( int* ptr, std::size_t count );
266
267 /*
268 Description:
269 Grows the array of doubles that was allocated by
270 GetDoubleMemory or GrowDoubleMemory.
271 Parameters:
272 ptr - [in] pointer returned by an earlier call to
273 GetDoubleMemory or GrowDoubleMemory.
274 count - [in] (>0) number of doubles in memory block.
275 If count <= 0, then NULL is returned.
276 If ptr was not allocated by this ON_Workspace
277 class, then NULL is returned.
278 Returns:
279 A pointer to the double array.
280 Remarks.
281 onrealloc() is used to grow the block of memory.
282 Do NOT free the pointer returned by GrowDoubleMemory().
283 ~ON_Workspace() will free the memory. If you decide
284 you want to keep the memory block, pass the pointer
285 to KeepMemory before ~ON_Workspace is called.
286 See Also:
287 ON_Workspace::GetDoubleMemory
288 ON_Workspace::KeepMemory
289 */
290 double* GrowDoubleMemory( double* ptr, std::size_t count );
291
292 /*
293 Description:
294 Grows the array of points that was allocated by
295 GetPointMemory or GrowPointMemory.
296 Parameters:
297 ptr - [in] pointer returned by an earlier call to
298 GetPointMemory or GrowPointMemory.
299 count - [in] (>0) number of points in memory block.
300 If count <= 0, then NULL is returned.
301 If ptr was not allocated by this ON_Workspace
302 class, then NULL is returned.
303 Returns:
304 A pointer to the point array.
305 Remarks.
306 onrealloc() is used to grow the block of memory.
307 Do NOT free the pointer returned by GrowMemory().
308 ~ON_Workspace() will free the memory. If you decide
309 you want to keep the memory block, pass the pointer
310 to KeepMemory before ~ON_Workspace is called.
311 See Also:
312 ON_Workspace::GetPointMemory
313 ON_Workspace::KeepMemory
314 */
315 ON_3dPoint* GrowPointMemory( ON_3dPoint* ptr, std::size_t count );
316
317 /*
318 Description:
319 Grows the array of vectors that was allocated by
320 GetVectorMemory or GrowVectorMemory.
321 Parameters:
322 ptr - [in] pointer returned by an earlier call to
323 GetVectorMemory or GrowVectorMemory.
324 count - [in] (>0) number of vectors in memory block.
325 If count <= 0, then NULL is returned.
326 If ptr was not allocated by this ON_Workspace
327 class, then NULL is returned.
328 Returns:
329 A pointer to the vector array.
330 Remarks.
331 onrealloc() is used to grow the block of memory.
332 Do NOT free the pointer returned by GrowMemory().
333 ~ON_Workspace() will free the memory. If you decide
334 you want to keep the memory block, pass the pointer
335 to KeepMemory before ~ON_Workspace is called.
336 See Also:
337 ON_Workspace::GetVectorMemory
338 ON_Workspace::KeepMemory
339 */
340 ON_3dVector* GrowVectorMemory( ON_3dVector* ptr, std::size_t count );
341
342 /*
343 Description:
344 Calling the KeepMemory() function with a pointer
345 returned from one of the Get...() or Grow...() calls
346 keeps the workspace destructor from freeing the memory.
347 After calling KeepMemory(), you can no longer use
348 Grow...() on the pointer. The caller is responsible
349 for using onfree() to release the memory when it is no
350 longer needed.
351 Parameters:
352 ptr - [in] pointer returned by a Get...() or Grow()
353 call to this ON_Workspace.
354 Returns:
355 True if the pointer was successfully found and removed
356 from this ON_Workspace.
357 See Also:
358 ON_Workspace::~ON_Workspace
359 ON_Workspace::GetMemory
360 ON_Workspace::KeepAllMemory
361 */
362 ON_BOOL32 KeepMemory( void* ptr );
363
364 /*
365 Description:
366 Calling KeepAllMemory() has the same effect as calling
367 KeepMemory(p) for every active allocation in the workspace.
368 After calling KeepAllMemory(), you can no longer use
369 Grow...() on the pointers and you are responsible
370 for using onfree() to release the memory when it is no
371 longer needed.
372 See Also:
373 ON_Workspace::~ON_Workspace
374 ON_Workspace::GetMemory
375 ON_Workspace::KeepMemory
376 */
378
379 /*
380 Description:
381 Uses ON::OpenFile to open a file. ~ON_Workspace will
382 close the file.
383 Parameters:
384 filename - [in] name of file
385 filemode - [in] open mode (just like second argument to fopen).
386 Returns:
387 Pointer to opened file.
388 Remarks:
389 ~ON_Workspace will close the file.
390 See Also:
391 ON_Workspace::~ON_Workspace
392 ON_Workspace::KeepFile
393 ON::OpenFile
394 */
395 FILE* OpenFile(
396 const char* filename,
397 const char* filemode
398 );
399
400 /*
401 Description:
402 Uses ON::OpenFile to open a file. ~ON_Workspace will
403 close the file.
404 Parameters:
405 filename - [in] name of file
406 filemode - [in] open mode (just like second argument to _wfopen).
407 Returns:
408 Pointer to opened file.
409 Remarks:
410 ~ON_Workspace will close the file.
411 See Also:
412 ON_Workspace::~ON_Workspace
413 ON_Workspace::KeepFile
414 ON::OpenFile
415 */
416 FILE* OpenFile(
417 const wchar_t* filename,
418 const wchar_t* filemode
419 );
420
421 /*
422 Description:
423 If you want to prevent ~ON_Workspace from closing a file
424 that was opened with ON_Workspace::OpenFile, then pass
425 the returned FILE pointer to KeepFile. After calling
426 KeepFile, the caller is responsible for calling
427 ON::CloseFile to close the file.
428 Parameters:
429 fileptr - [in] pointer returned by OpenFile.
430 Returns:
431 True if file was successfully closed.
432 See Also:
433 ON_Workspace::~ON_Workspace
434 ON_Workspace::OpenFile
435 ON::OpenFile
436 ON::CloseFile
437 */
438 int KeepFile(FILE* fileptr);
439
440private:
441 struct ON_Workspace_FBLK * m_pFileBlk;
442 struct ON_Workspace_MBLK * m_pMemBlk;
443
444private:
445 // There is no implementation of the following to prevent use.
446 // ON_Workspaces should never be copied, or you will get
447 // multiple attempts to free the same pointer.
448 ON_Workspace( const ON_Workspace& );
449 ON_Workspace& operator=( const ON_Workspace& );
450};
451
452
453#endif
ON_3dPoint * GetPointMemory(std::size_t count)
FILE * OpenFile(const char *filename, const char *filemode)
int KeepFile(FILE *fileptr)
void KeepAllMemory()
ON_3dVector * GetVectorMemory(std::size_t count)
void * GrowMemory(void *ptr, std::size_t sz)
ON_3dVector * GrowVectorMemory(ON_3dVector *ptr, std::size_t count)
void Destroy()
void * GetMemory(std::size_t sz)
ON_BOOL32 KeepMemory(void *ptr)
double * GetDoubleMemory(std::size_t count)
int * GetIntMemory(std::size_t count)
double * GrowDoubleMemory(double *ptr, std::size_t count)
FILE * OpenFile(const wchar_t *filename, const wchar_t *filemode)
int * GrowIntMemory(int *ptr, std::size_t count)
int ** GetIntMemory(std::size_t row_count, std::size_t col_count)
double ** GetDoubleMemory(std::size_t row_count, std::size_t col_count)
ON_3dPoint * GrowPointMemory(ON_3dPoint *ptr, std::size_t count)