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