Memory Management
[Base Functionality]

Collaboration diagram for Memory Management:


Classes
class	ACIS_OBJECT
	Provides a base class for class level memory management of ACIS classes. More...
class	base_configuration
	The base configuration object. More...
class	minimize_options
	Supplies the specific minimization actions to `api_minimize_entities`. More...
struct	page_statistics
	The page system statistics. More...
Defines
#define	ACIS_ALLOCA(alloc_size) (((alloc_size) > 8) ? alloca((alloc_size)) : alloca(8))
	ACIS wrapper for alloca.
#define	ACIS_CALLOC(alloc_num, alloc_size) acis_calloc(alloc_num,alloc_size,eDefault,__FILE__,__LINE__,&alloc_file_index);
	ACIS wrapper for calloc.
#define	ACIS_DELETE delete
	ACIS wrapper for C++ delete - Complements `ACIS_NEW`.
#define	ACIS_FREE(alloc_ptr) acis_free(alloc_ptr);
	ACIS wrapper for free.
#define	ACIS_MALLOC(alloc_size) acis_malloc(alloc_size,eDefault,__FILE__,__LINE__,&alloc_file_index);
	ACIS wrapper for malloc.
#define	ACIS_NEW new(eDefault,__FILE__,__LINE__,&alloc_file_index)
	ACIS wrapper for C++ new - Complements `ACIS_DELETE`.
#define	ACIS_REALLOC(memblock, alloc_size) acis_realloc(memblock,alloc_size,eDefault,__FILE__,__LINE__,&alloc_file_index);
	ACIS wrapper for realloc.
#define	ACIS_SAFE_REALLOC(memblock, old_size, new_size) acis_safe_realloc(memblock,old_size,new_size,eDefault,__FILE__,__LINE__,&alloc_file_index);
	ACIS wrapper for realloc.
#define	ACIS_STRDUP(orgstring) acis_strdup(orgstring,eDefault,__FILE__,__LINE__,&alloc_file_index);
	ACIS wrapper for strdup.
#define	MMGR_FREELIST_THIS
	Use this macro inside your class definition to enhance your class with ACIS memory management and ACIS freelisting.
#define	MMGR_SUPPORT_THIS
	Use this macro inside your class definition to enhance your class with ACIS memory management.
#define	STD_CAST (ACIS_STD_TYPE_OBJECT*)
	Informs the ACIS memory manager that a simple data type is being deleted.
Typedefs
typedef void (	complex_allocator_fn )(size_t size, AcisMemType alloc_type, AcisMemCall alloc_call, const char alloc_file, int alloc_line, int alloc_file_index)
	Prototype of the complex allocator.
typedef void(*	complex_destructor_fn )(void *SPAptr, AcisMemCall alloc_call, size_t size)
	Prototype of the complex destructor.
typedef void (	raw_allocator_fn )(size_t size)
	Prototype of the raw allocator.
typedef void(*	raw_destructor_fn )(void *SPAptr)
	Prototype of the raw destructor.
Enumerations
enum	AcisMemCall
	Specifies the style of allocation. More...
enum	AcisMemType
	Specifies the persistence of memory allocated via the ACIS memory manager. More...
Functions
outcome	api_minimize_entities (ENTITY_LIST list, minimize_options mo=NULL, AcisOptions *ao=NULL)
	Attempts to minimize the working memory footprint of the input entities.
outcome	api_set_default_minimize_options (minimize_options *mo)
	Set the default minimization actions.
outcome	api_stackmon_limit (size_t limit)
	Sets the limit in bytes of how much stack ACIS may use.
void	clear_all_free_lists ()
	Instruct the memory manager to release all empty freelist data blocks.
void	collapse_all_free_lists ()
	Set the state of the memory manager to release empty freelist data blocks.
const char *	get_page_file_name ()
	Get the page file name.
page_statistics const *	get_page_statistics ()
	Get the page system statistics.
page_system_state	get_page_system_state ()
	Get the page system state.
size_t	initialize_page_system (FILE *page_file, page_run_mode run_mode=PS_EMPTY_DELETE)
	Initialize the page system used by api_minimize_entities.
size_t	initialize_page_system (char *page_file_name=NULL, page_run_mode run_mode=PS_EMPTY_DELETE)
	Initialize the page system used by api_minimize_entities.
void	keep_all_free_lists ()
	Set the state of the memory manager to keep all freelist data blocks until the application terminates.
page_system_state	terminate_page_system ()
	Terminate the page system used by api_minimize_entities.

Define Documentation

#define ACIS_ALLOCA ( alloc_size ) (((alloc_size) > 8) ? alloca((alloc_size)) : alloca(8))

ACIS wrapper for alloca.

Parameters:

alloc_size

number of bytes to allocate from stack.

include <mmgr.hxx>

#define ACIS_CALLOC	(	alloc_num,
		alloc_size		)	acis_calloc(alloc_num,alloc_size,eDefault,__FILE__,__LINE__,&alloc_file_index);

ACIS wrapper for calloc.

Parameters:

	alloc_num	number of elements to allocate.
	alloc_size	number of bytes to allocate.

See also:: ACIS_FREE

include <mmgr.hxx>

#define ACIS_DELETE delete

ACIS wrapper for C++ delete - Complements ACIS_NEW.

See also:: ACIS_NEW, STD_CAST

include <mmgr.hxx>

#define ACIS_FREE ( alloc_ptr ) acis_free(alloc_ptr);

ACIS wrapper for free.

Parameters:

alloc_ptr

pointer to memory to be freed.

See also:: ACIS_MALLOC, ACIS_CALLOC, ACIS_SAFE_REALLOC, ACIS_STRDUP

include <mmgr.hxx>

#define ACIS_MALLOC ( alloc_size ) acis_malloc(alloc_size,eDefault,__FILE__,__LINE__,&alloc_file_index);

ACIS wrapper for malloc.

Parameters:

alloc_size

number of bytes to allocate.

See also:: ACIS_FREE

include <mmgr.hxx>

#define ACIS_NEW new(eDefault,__FILE__,__LINE__,&alloc_file_index)

ACIS wrapper for C++ new - Complements ACIS_DELETE.

See also:: ACIS_DELETE

include <mmgr.hxx>

#define ACIS_REALLOC	(	memblock,
		alloc_size		)	acis_realloc(memblock,alloc_size,eDefault,__FILE__,__LINE__,&alloc_file_index);

ACIS wrapper for realloc.

Parameters:

	memblock	pointer to original memory block.
	alloc_size	number of bytes to allocate.

See also:: ACIS_SAFE_REALLOC, ACIS_FREE

include <mmgr.hxx>

#define ACIS_SAFE_REALLOC	(	memblock,
		old_size,
		new_size	)	acis_safe_realloc(memblock,old_size,new_size,eDefault,__FILE__,__LINE__,&alloc_file_index);

ACIS wrapper for realloc.

Parameters:

	memblock	pointer to original memory block.
	old_size	size of original memory block.
	new_size	number of bytes to allocate.

See also:: ACIS_REALLOC, ACIS_FREE

include <mmgr.hxx>

#define ACIS_STRDUP ( orgstring ) acis_strdup(orgstring,eDefault,__FILE__,__LINE__,&alloc_file_index);

ACIS wrapper for strdup.

Parameters:

orgstring

string to copy.

See also:: ACIS_FREE

include <mmgr.hxx>

#define MMGR_FREELIST_THIS

Value:

MMGR_STL_SUPPORT \
        MMGR_DEBUG_NEW_SUPPORT \
        MMGR_BASIC_FREELIST_SUPPORT \
        MMGR_EXTENDED_FREELIST_SUPPORT \
        MMGR_FREELIST_EXCEPTION_SUPPORT

Use this macro inside your class definition to enhance your class with ACIS memory management and ACIS freelisting.

See also:: MMGR_SUPPORT_THIS, ACIS_OBJECT

include <mmgr.hxx>

#define MMGR_SUPPORT_THIS

Value:

MMGR_STL_SUPPORT \
        MMGR_DEBUG_NEW_SUPPORT \
        MMGR_NO_FREELIST_SUPPORT \
        MMGR_NO_FREELIST_EXCEPTION_SUPPORT

Use this macro inside your class definition to enhance your class with ACIS memory management.

Note: does not provide support for ACIS freelisting.

See also:: MMGR_FREELIST_THIS, ACIS_OBJECT

include <mmgr.hxx>

#define STD_CAST (ACIS_STD_TYPE_OBJECT*)

Informs the ACIS memory manager that a simple data type is being deleted.

Role: When deleting a simple data type using ACIS_DELETE, you must use the STD_CAST macro.

By using the STD_CAST macro, the ACIS memory management system can intercept the call and we will successfully track the memory.

Do not use STD_CAST on anything but simple data types. Doing so may result in your application crashing.

Here are some examples:

 double * pd = ACIS_NEW double;
 ACIS_DELETE STD_CAST pd;


 double * dlist = ACIS_NEW double[14];
 ACIS_DELETE [] STD_CAST dlist;


 SPAposition *ppos = ACIS_NEW SPAposition;
 ACIS_DELETE ppos;	// STD_CAST not needed! Not a simple data type.


 SPAposition **pppos = ACIS_NEW SPAposition *;
 ACIS_DELETE STD_CAST pppos;	// STD_CAST is needed - we're deleting a pointer.

include <mmgr.hxx>

Typedef Documentation

typedef void*(* complex_allocator_fn)(size_t size, AcisMemType alloc_type, AcisMemCall alloc_call, const char *alloc_file, int alloc_line, int *alloc_file_index)

Prototype of the complex allocator.

Parameters:

	size	Size of allocation.
	alloc_type	Type of allocation.
	alloc_call	Style of allocation.
	alloc_file	File that performed the allocation (usually __FILE__).
	alloc_line	Line number of allocation (usually __LINE__).
	alloc_file_index	Must be '&alloc_file_index'.

include <base.hxx>

typedef void(* complex_destructor_fn)(void *SPAptr, AcisMemCall alloc_call, size_t size)

Prototype of the complex destructor.

Parameters:

	SPAptr	Pointer to memory to be freed.
	alloc_call	Style of deallocation.
	size	Size of deallocation.

include <base.hxx>

typedef void*(* raw_allocator_fn)(size_t size)

Prototype of the raw allocator.

Parameters:

size

Size of allocation.

include <base.hxx>

typedef void(* raw_destructor_fn)(void *SPAptr)

Prototype of the raw destructor.

Parameters:

SPAptr

Pointer to memory to be freed.

include <base.hxx>

Enumeration Type Documentation

enum AcisMemCall

Specifies the style of allocation.

enum AcisMemType

Specifies the persistence of memory allocated via the ACIS memory manager.

Parameters:

	eDefault	default memory persistence.
	eSession	session memory persistence.
	eDocument	document memory persistence.
	eTemporary	temporary memory persistence.

include <mmgr.hxx>

Function Documentation

outcome api_minimize_entities	(	ENTITY_LIST *	list,
		minimize_options *	mo = `NULL`,
		AcisOptions *	ao = `NULL`
	)

Attempts to minimize the working memory footprint of the input entities.

Role: Applies the default minimization actions, or the specific actions of the optional minimize_options object, on the geometry of the input entities. This API allows you to page geometric data to disk and to delete lazy approximations, which can drastically reduce the working memory footprint of the model. The paged geometric data is automatically unpaged and the lazy data is automatically recalculated when needed. The input entities are scanned downward, which allows you to be very specific as to which geometry is to be affected. When the input entity is a face, for example, then only the geometry of that face's edges and coedges are minimized. In contrast, given a body input entity, all the geometry is to be minimized. The location and name of the page file can be set with the initialize_page_system function. The effectiveness of the paging system can be evaluated with the get_page_statistics function.

Note: The default actions enable paging.

Effect: Read-only

Journal: Not Available

Product(s): 3D ACIS Exchange, 3D Viz Exchange, 3D ACIS Modeler

Parameters:

	list	input entities
	mo	minimization options
	ao	ACIS options

See also:: minimize_options, initialize_page_system, get_page_statistics

include <kernapi.hxx>

outcome api_set_default_minimize_options ( minimize_options * mo )

Set the default minimization actions.

Role: The minimize_options object supplied to api_minimize_entities is optional. The default actions are used when not supplied to the API, when surfaces and curves transition into history, and when curves and surfaces are restored from an ACIS save file. When a surface is lost, for example, its geometric data will be minimized based upon the default minimize options actions. The default minimize options enable the paging of all geometry, including lazy approximations. Specifying default actions with this API will enable automatic history minimization if the page system is initialized.

Note: The default actions enable paging.

Effect: Read-only

Journal: Not Available

Product(s): 3D ACIS Exchange, 3D Viz Exchange, 3D ACIS Modeler

Parameters:

mo

minimization options

See also:: api_minimize_entities, minimize_options, initialize_page_system, get_page_statistics

include <kernapi.hxx>

outcome api_stackmon_limit ( size_t limit )

Sets the limit in bytes of how much stack ACIS may use.

Role: ACIS can monitor the size of the stack. This function sets the limit in bytes of how much stack ACIS may use. If the limit is exceeded, ACIS will trap, returning EXCESSIVE_RECURSION. Passing 0 results in no stack monitoring.

Effect: Read-only

Journal: Not Available

Product(s): 3D ACIS Exchange, 3D Viz Exchange, 3D ACIS Modeler

Parameters:

limit

bytes of stack memory.

include <kernapi.hxx>

void clear_all_free_lists ( )

Instruct the memory manager to release all empty freelist data blocks.

Role: The ACIS freelist mechanism uses 4k data blocks from which smaller chunks are taken. Calling this function instructs the freelist mechanism to free any 4k data blocks that are currently not in use. This gives the application control to return unused freelist data blocks when the application thinks appropriate.

See also:: collapse_all_free_lists, clear_all_free_lists, keep_all_free_lists

include <freelist.hxx>

void collapse_all_free_lists ( )

Set the state of the memory manager to release empty freelist data blocks.

Role: The ACIS freelist mechanism uses 4k data blocks from which smaller chunks are taken. Calling this function instructs the freelist mechanism to free those 4k data blocks when they are empty. You only need to call this function once to set the memory manager to this operational state.

See also:: collapse_all_free_lists, clear_all_free_lists, keep_all_free_lists

include <freelist.hxx>

const char* get_page_file_name ( )

Get the page file name.

Role: Returns the current page file name.

See also:: page_statistics, api_minimize_entities

include <pageman.hxx>

page_statistics const* get_page_statistics ( )

Get the page system statistics.

Role: Returns a pointer to the page_statistics object owned by the page system. The object contains information that may be useful to determine the effectiveness of memory minimization.

See also:: page_statistics, api_minimize_entities

include <pageman.hxx>

page_system_state get_page_system_state ( )

Get the page system state.

Role: Returns a page_system_state enumeration type. The possible states are UNINITIALIZED, ACTIVE, or SUSPENDED.

See also:: page_statistics, api_minimize_entities

include <pageman.hxx>

size_t initialize_page_system	(	FILE *	page_file,
		page_run_mode	run_mode = `PS_EMPTY_DELETE`
	)

Initialize the page system used by api_minimize_entities.

Role: Use this function to initialize the page system with a file handle. The input file must be opened to allow both read and write operations in untranslated binary mode. We suggest access modes "rb+" or "wb+". The page system will begin writing at the current write location and will reset to this location during termination. The file will not be closed or deleted. One can also specify the action the paging system takes when the page file reaches an empty state. By default, the action is set to delete all records and reinitialize the paging system. The other option is to retain all records in the page file.

Parameters:

	page_file	file handle of the page file
	run_mode	the action to take when the page file reaches an empty state

include <pageman.hxx>

size_t initialize_page_system	(	char *	page_file_name = `NULL`,
		page_run_mode	run_mode = `PS_EMPTY_DELETE`
	)

Initialize the page system used by api_minimize_entities.

Role: Use this function to initialize the page system with a file name. One can specify the name and location of the file to use. The system will by default create a file called acis.swp in the current working directory, if another name has not been specified. The swap file is created by the paging system during initialization and is deleted during termination. One can also specify the action the paging system takes when the page file reaches an empty state. By default, the action is set to delete all records and reinitialize the paging system. The other option is to retain all records in the page file.

Parameters:

	page_file_name	the name of the page file
	run_mode	the action to take when the page file reaches an empty state

include <pageman.hxx>

void keep_all_free_lists ( )

Set the state of the memory manager to keep all freelist data blocks until the application terminates.

Role: The ACIS freelist mechanism uses 4k data blocks from which smaller chunks are taken. Calling this function instructs the freelist mechanism to keep all freelist data blocks, even those that are empty. Hence, the freelists simply will continue to grow even if all memory has been returned to the freelist. You only need to call this function once to set the memory manager to this operational state.

See also:: collapse_all_free_lists, clear_all_free_lists, keep_all_free_lists

include <freelist.hxx>

page_system_state terminate_page_system ( )

Terminate the page system used by api_minimize_entities.

Role: Use this function to terminate or suspend the page system. If the page file is no longer needed, this command will close all open files and deallocate all memory associated with the page system. If the page file is not empty, the page system is set to a suspended state where entities stored in the page file may be restored, but new entries are not saved to the file. The return value indicates the state of the page system after executing this command. Possible values of page_system_state enumeration type are UNINITIALIZED, ACTIVE, or SUSPENDED.

include <pageman.hxx>

Memory Management [Base Functionality]

Classes

Defines

Typedefs

Enumerations

Functions

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Memory Management
[Base Functionality]