Page MenuHome
Differential D6807 Diff 21591 extern/opennurbs/opennurbs_workspace.h

Changeset View

Standalone View

View Options

extern/opennurbs/opennurbs_workspace.h

  • This file was added.
/* $NoKeywords: $ */
/*
//
// Copyright (c) 1993-2012 Robert McNeel & Associates. All rights reserved.
// OpenNURBS, Rhinoceros, and Rhino3D are registered trademarks of Robert
// McNeel & Associates.
//
// THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT EXPRESS OR IMPLIED WARRANTY.
// ALL IMPLIED WARRANTIES OF FITNESS FOR ANY PARTICULAR PURPOSE AND OF
// MERCHANTABILITY ARE HEREBY DISCLAIMED.
//
// For complete openNURBS copyright information see <http://www.opennurbs.org>.
//
////////////////////////////////////////////////////////////////
*/
#if !defined(OPENNURBS_WORKSPACE_INC_)
#define OPENNURBS_WORKSPACE_INC_
/*
Description:
Use ON_Workspace classes on the stack to efficiently get
and automatically clean up workspace memory and scratch
files.
*/
class ON_CLASS ON_Workspace
{
public:
/*
Description:
ON_Workspace classes should be on the stack
or as members on classes that are never copied.
The destructor frees memory that was allocated by
ON_Workspace::GetMemory and closes files that were
opened with ON_Workspace::OpenFile.
*/
ON_Workspace();
/*
Description:
The destructor frees memory that was allocated by
ON_Workspace::GetMemory and closes files that were
opened with ON_Workspace::OpenFile.
*/
~ON_Workspace();
/*
Description:
The destructor frees memory that was allocated by
ON_Workspace::GetMemory and closes files that were
opened with ON_Workspace::OpenFile. The workspace
can be used again after calling destroy.
*/
void Destroy();
/*
Description:
Gets a block of heap memory that will be freed by
~ON_Workspace. The intent of ON_Workspace::GetMemory
is to provide an easy way to get blocks of scratch
memory without having to worry about cleaning up
before returning.
Parameters:
sz - [in] (>0) size of memory block in bytes.
If sz <= 0, then NULL is returned.
Returns:
A pointer to the memory block.
Remarks.
onmalloc() is used to get the block of memory.
Do NOT free the pointer returned by GetMemory().
~ON_Workspace() will free the memory. If you decide
you want to keep the memory block, pass the pointer
to KeepMemory before ~ON_Workspace is called.
See Also:
ON_Workspace::::~ON_Workspace
ON_Workspace::KeepMemory
ON_Workspace::GrowMemory
ON_Workspace::GetIntMemory
ON_Workspace::GetDoubleMemory
ON_Workspace::GetPointMemory
ON_Workspace::GetVectorMemory
*/
void* GetMemory( size_t sz );
/*
Description:
Gets an array of integers that will be freed by ~ON_Workspace.
The intent of ON_Workspace::GetIntMemory is to provide
an easy way to get scratch integer arrays without
having to worry about cleaning up before returning.
Parameters:
count - [in] (>0) number of integers in memory block.
If count <= 0, then NULL is returned.
Returns:
A pointer to the array of integers.
Remarks.
This is a simple helper function so you don't have to
mess around with (int*) casts and sizeof(int)s in a call
to GetMemory(). It is exactly like calling
(int*)GetMemory(count*sizeof(int));
See Also:
ON_Workspace::GetMemory
ON_Workspace::KeepMemory
ON_Workspace::GrowIntMemory
*/
int* GetIntMemory( size_t count );
/*
Description:
Gets an matrix of integers
Parameters:
row_count - [in] (>0) number of rows
col_count - [in] (>0) number of columns
Returns:
A pointer p so that p[i][j] is an integer when
0 <= i < row_count and 0 <= j < col_count.
Remarks.
This is a simple helper function so you don't have to
mess around building the 2d array.
See Also:
ON_Workspace::KeepMemory
*/
int** GetIntMemory( size_t row_count, size_t col_count );
/*
Description:
Gets an array of doubles that will be freed by ~ON_Workspace.
The intent of ON_Workspace::GetDoubleMemory is to provide
an easy way to get scratch double arrays without
having to worry about cleaning up before returning.
Parameters:
count - [in] (>0) number of doubles in memory block.
If count <= 0, then NULL is returned.
Returns:
A pointer to the array of doubles.
Remarks.
This is a simple helper function so you don't have to
mess around with (double*) casts and sizeof(double)s
in a call to GetMemory(). It is exactly like calling
(double*)GetMemory(count*sizeof(double));
See Also:
ON_Workspace::GetMemory
ON_Workspace::KeepMemory
ON_Workspace::GrowIntMemory
*/
double* GetDoubleMemory( size_t count );
/*
Description:
Gets an matrix of doubles
Parameters:
row_count - [in] (>0) number of rows
col_count - [in] (>0) number of columns
Returns:
A pointer p so that p[i][j] is an double when
0 <= i < row_count and 0 <= j < col_count.
Remarks.
This is a simple helper function so you don't have to
mess around building the 2d array.
See Also:
ON_Workspace::KeepMemory
*/
double** GetDoubleMemory( size_t row_count, size_t col_count );
/*
Description:
Gets an array of ON_3dPoints that will be freed by ~ON_Workspace.
The intent of ON_Workspace::GetPointMemory is to
provide an easy way to get scratch point arrays without
having to worry about cleaning up before returning.
Parameters:
count - [in] (>0) number of points in memory block.
If count <= 0, then NULL is returned.
Returns:
A pointer to the memory block.
Remarks.
This is a simple helper function so you don't have to
mess around with (ON_3dPoint*) casts and sizeof(ON_3dPoint)s
in a call to GetMemory(). It is exactly like calling
(ON_3dPoint*)GetMemory(count*sizeof(ON_3dPoint));
See Also:
ON_Workspace::GetMemory
ON_Workspace::KeepMemory
ON_Workspace::GrowIntMemory
*/
ON_3dPoint* GetPointMemory( size_t count );
/*
Description:
Gets an array of ON_3dVectors that will be freed by ~ON_Workspace.
The intent of ON_Workspace::GetVectorMemory is to
provide an easy way to get scratch Vector arrays without
having to worry about cleaning up before returning.
Parameters:
count - [in] (>0) number of Vectors in memory block.
If count <= 0, then NULL is returned.
Returns:
A pointer to the memory block.
Remarks.
This is a simple helper function so you don't have to
mess around with (ON_3dVector*) casts and sizeof(ON_3dVector)s
in a call to GetMemory(). It is exactly like calling
(ON_3dVector*)GetMemory(count*sizeof(ON_3dVector));
See Also:
ON_Workspace::GetMemory
ON_Workspace::KeepMemory
ON_Workspace::GrowIntMemory
*/
ON_3dVector* GetVectorMemory( size_t count );
/*
Description:
Grows a block of heap memory that was allocated by
ON_Workspace::GetMemory.
Parameters:
ptr - [in] pointer returned by an earlier call to
GetMemory or GrowMemory.
sz - [in] (>0) size of memory block in bytes.
If sz <= 0, then NULL is returned.
If ptr is not NULL and was not allocated by an
earlier call to GetMemory or GrowMemory, then
NULL is returned.
Returns:
A pointer to the memory block.
Remarks.
onrealloc() is used to grow the block of memory.
Do NOT free the pointer returned by GrowMemory().
~ON_Workspace() will free the memory. If you decide
you want to keep the memory block, pass the pointer
to KeepMemory before ~ON_Workspace is called.
See Also:
ON_Workspace::GetMemory
ON_Workspace::KeepMemory
ON_Workspace::GrowIntMemory
ON_Workspace::GrowDoubleMemory
ON_Workspace::GrowPointMemory
ON_Workspace::GrowVectorMemory
*/
void* GrowMemory( void* ptr, size_t sz );
/*
Description:
Grows the array of integers that was allocated by
GetIntMemory or GrowIntMemory.
Parameters:
ptr - [in] pointer returned by an earlier call to
GetIntMemory or GrowIntMemory.
count - [in] (>0) number of integers in memory block.
If count <= 0, then NULL is returned.
If ptr was not allocated by this ON_Workspace
class, then NULL is returned.
Returns:
A pointer to the integer array.
Remarks.
onrealloc() is used to grow the block of memory.
Do NOT free the pointer returned by GrowIntMemory().
~ON_Workspace() will free the memory. If you decide
you want to keep the memory block, pass the pointer
to KeepMemory before ~ON_Workspace is called.
See Also:
ON_Workspace::GetIntMemory
ON_Workspace::KeepMemory
*/
int* GrowIntMemory( int* ptr, size_t count );
/*
Description:
Grows the array of doubles that was allocated by
GetDoubleMemory or GrowDoubleMemory.
Parameters:
ptr - [in] pointer returned by an earlier call to
GetDoubleMemory or GrowDoubleMemory.
count - [in] (>0) number of doubles in memory block.
If count <= 0, then NULL is returned.
If ptr was not allocated by this ON_Workspace
class, then NULL is returned.
Returns:
A pointer to the double array.
Remarks.
onrealloc() is used to grow the block of memory.
Do NOT free the pointer returned by GrowDoubleMemory().
~ON_Workspace() will free the memory. If you decide
you want to keep the memory block, pass the pointer
to KeepMemory before ~ON_Workspace is called.
See Also:
ON_Workspace::GetDoubleMemory
ON_Workspace::KeepMemory
*/
double* GrowDoubleMemory( double* ptr, size_t count );
/*
Description:
Grows the array of points that was allocated by
GetPointMemory or GrowPointMemory.
Parameters:
ptr - [in] pointer returned by an earlier call to
GetPointMemory or GrowPointMemory.
count - [in] (>0) number of points in memory block.
If count <= 0, then NULL is returned.
If ptr was not allocated by this ON_Workspace
class, then NULL is returned.
Returns:
A pointer to the point array.
Remarks.
onrealloc() is used to grow the block of memory.
Do NOT free the pointer returned by GrowMemory().
~ON_Workspace() will free the memory. If you decide
you want to keep the memory block, pass the pointer
to KeepMemory before ~ON_Workspace is called.
See Also:
ON_Workspace::GetPointMemory
ON_Workspace::KeepMemory
*/
ON_3dPoint* GrowPointMemory( ON_3dPoint* ptr, size_t count );
/*
Description:
Grows the array of vectors that was allocated by
GetVectorMemory or GrowVectorMemory.
Parameters:
ptr - [in] pointer returned by an earlier call to
GetVectorMemory or GrowVectorMemory.
count - [in] (>0) number of vectors in memory block.
If count <= 0, then NULL is returned.
If ptr was not allocated by this ON_Workspace
class, then NULL is returned.
Returns:
A pointer to the vector array.
Remarks.
onrealloc() is used to grow the block of memory.
Do NOT free the pointer returned by GrowMemory().
~ON_Workspace() will free the memory. If you decide
you want to keep the memory block, pass the pointer
to KeepMemory before ~ON_Workspace is called.
See Also:
ON_Workspace::GetVectorMemory
ON_Workspace::KeepMemory
*/
ON_3dVector* GrowVectorMemory( ON_3dVector* ptr, size_t count );
/*
Description:
Calling the KeepMemory() function with a pointer
returned from one of the Get...() or Grow...() calls
keeps the workspace destructor from freeing the memory.
After calling KeepMemory(), you can no longer use
Grow...() on the pointer. The caller is responsible
for using onfree() to release the memory when it is no
longer needed.
Parameters:
ptr - [in] pointer returned by a Get...() or Grow()
call to this ON_Workspace.
Returns:
True if the pointer was successfully found and removed
from this ON_Workspace.
See Also:
ON_Workspace::~ON_Workspace
ON_Workspace::GetMemory
ON_Workspace::KeepAllMemory
*/
ON_BOOL32 KeepMemory( void* ptr );
/*
Description:
Calling KeepAllMemory() has the same effect as calling
KeepMemory(p) for every active allocation in the workspace.
After calling KeepAllMemory(), you can no longer use
Grow...() on the pointers and you are responsible
for using onfree() to release the memory when it is no
longer needed.
See Also:
ON_Workspace::~ON_Workspace
ON_Workspace::GetMemory
ON_Workspace::KeepMemory
*/
void KeepAllMemory();
/*
Description:
Uses ON::OpenFile to open a file. ~ON_Workspace will
close the file.
Parameters:
filename - [in] name of file
filemode - [in] open mode (just like second argument to fopen).
Returns:
Pointer to opened file.
Remarks:
~ON_Workspace will close the file.
See Also:
ON_Workspace::~ON_Workspace
ON_Workspace::KeepFile
ON::OpenFile
*/
FILE* OpenFile(
const char* filename,
const char* filemode
);
/*
Description:
Uses ON::OpenFile to open a file. ~ON_Workspace will
close the file.
Parameters:
filename - [in] name of file
filemode - [in] open mode (just like second argument to _wfopen).
Returns:
Pointer to opened file.
Remarks:
~ON_Workspace will close the file.
See Also:
ON_Workspace::~ON_Workspace
ON_Workspace::KeepFile
ON::OpenFile
*/
FILE* OpenFile(
const wchar_t* filename,
const wchar_t* filemode
);
/*
Description:
If you want to prevent ~ON_Workspace from closing a file
that was opened with ON_Workspace::OpenFile, then pass
the returned FILE pointer to KeepFile. After calling
KeepFile, the caller is responsible for calling
ON::CloseFile to close the file.
Parameters:
fileptr - [in] pointer returned by OpenFile.
Returns:
True if file was successfully closed.
See Also:
ON_Workspace::~ON_Workspace
ON_Workspace::OpenFile
ON::OpenFile
ON::CloseFile
*/
int KeepFile(FILE* fileptr);
private:
struct ON_Workspace_FBLK * m_pFileBlk;
struct ON_Workspace_MBLK * m_pMemBlk;
private:
// There is no implementation of the following to prevent use.
// ON_Workspaces should never be copied, or you will get
// multiple attempts to free the same pointer.
ON_Workspace( const ON_Workspace& );
ON_Workspace& operator=( const ON_Workspace& );
};
#endif