Point Cloud Library (PCL)  1.14.1-dev
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 /*
21 Description:
22  Use ON_Workspace classes on the stack to efficiently get
23  and automatically clean up workspace memory and scratch
24  files.
25 */
26 class ON_CLASS ON_Workspace
27 {
28 public:
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  */
37  ON_Workspace();
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  */
45  ~ON_Workspace();
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  */
377  void KeepAllMemory();
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 
440 private:
441  struct ON_Workspace_FBLK * m_pFileBlk;
442  struct ON_Workspace_MBLK * m_pMemBlk;
443 
444 private:
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
Definition: opennurbs_point.h:419
ON_3dVector
Definition: opennurbs_point.h:953
ON_Workspace
Definition: opennurbs_workspace.h:27
ON_Workspace::GetMemory
void * GetMemory(std::size_t sz)
ON_Workspace::GetIntMemory
int * GetIntMemory(std::size_t count)
ON_Workspace::GrowVectorMemory
ON_3dVector * GrowVectorMemory(ON_3dVector *ptr, std::size_t count)
ON_Workspace::KeepFile
int KeepFile(FILE *fileptr)
ON_Workspace::KeepAllMemory
void KeepAllMemory()
ON_Workspace::ON_Workspace
ON_Workspace()
ON_Workspace::GetIntMemory
int ** GetIntMemory(std::size_t row_count, std::size_t col_count)
ON_Workspace::Destroy
void Destroy()
ON_Workspace::OpenFile
FILE * OpenFile(const char *filename, const char *filemode)
ON_Workspace::KeepMemory
ON_BOOL32 KeepMemory(void *ptr)
ON_Workspace::GetDoubleMemory
double ** GetDoubleMemory(std::size_t row_count, std::size_t col_count)
ON_Workspace::~ON_Workspace
~ON_Workspace()
ON_Workspace::OpenFile
FILE * OpenFile(const wchar_t *filename, const wchar_t *filemode)
ON_Workspace::GetVectorMemory
ON_3dVector * GetVectorMemory(std::size_t count)
ON_Workspace::GrowPointMemory
ON_3dPoint * GrowPointMemory(ON_3dPoint *ptr, std::size_t count)
ON_Workspace::GetPointMemory
ON_3dPoint * GetPointMemory(std::size_t count)
ON_Workspace::GrowMemory
void * GrowMemory(void *ptr, std::size_t sz)
ON_Workspace::GetDoubleMemory
double * GetDoubleMemory(std::size_t count)
ON_Workspace::GrowDoubleMemory
double * GrowDoubleMemory(double *ptr, std::size_t count)
ON_Workspace::GrowIntMemory
int * GrowIntMemory(int *ptr, std::size_t count)