NCL Home > Documentation > HLUs > Classes

Workspace class

The Workspace object manages large blocks of memory on behalf of a number of HLU library objects.

Synopsis

Header file:		ncarg/hlu/Workspace.h
Class name:		workspaceClass
Class pointer:		<Not referenceable>
Fortran class function:	<Not referenceable>
Superclass:		Obj
Composite classes:	<None>

Resources

Local resources

+---------------------------------------------------------------+
|			Workspace Resource Set			|
|---------------------------------------------------------------|
| NAME				TYPE			ACCESS	|
|	CLASS				DEFAULT			|
|===============================================================|
| wsMaximumSize                 NhlTLong                RCSG    |
|       WsMaximumSize                   16777216                |
|---------------------------------------------------------------|
| wsThresholdSize               NhlTLong                RCSG    |
|       WsThresholdSize                 4194304                 |
|---------------------------------------------------------------|
| wsCurrentSize                 NhlTLong                RCSG    |
|       WsCurrentSize                   0                       |
+---------------------------------------------------------------+

Composite resources

The Workspace object class has no composite class objects.

Superclass resources

The superclass of the Workstation object class does not define any resources.

Description

The Workspace object manages large blocks of memory, known as workspaces, that a number of the low-level routines require in order to perform their function. It does not manage the dynamic memory needed for the instantiation of the HLU object themselves. The Workspace object class is like the Error object class in that each HLU program creates one and only one object of this class. This single global Workstation object manages the workspace needs of all HLU plot objects. As a user, you are allowed neither to create nor destroy a Workspace object. You may, however, set and retrieve several Workspace resources.

Most of the time, the Workspace object operates transparently, and you do not need to be concerned with how it works. However, based on the memory resources available to your processes, you may wish to tune the performance of your HLU applications by adjusting the resources of the Workspace object. Since you do not create the Workspace, you cannot get or set any of its resources without first retrieving its object id through a call to the support function NhlGetWorkspaceObjectId.

In order to use the resources of the Workspace object effectively, you should know a little bit about its operation. Plot objects may create and destroy workspaces. Once created, a workspace may be in one of two states: in use or idle. The Workspace object keeps track of the total number of bytes currently allocated for workspaces. You can retrieve this value at any time (after you get the Workspace object id) by getting the value of the resource wsCurrentSize. Any time a plot object requests to use a workspace, the Workspace object checks to see if the request would cause the number of currently allocated bytes to go over a threshold value, as set by the resource wsThresholdSize. If so, the Workspace object looks through the list of idle workspaces, freeing space until either the size of the requested space added to the remaining space no longer causes wsThresholdSize to be exceeded or no more idle workspaces remain. Note that the HLU writer can specify that the contents of a workspace be preserved. In this case, the Workspace object writes the contents of the workspace to a file before freeing the space.

Notice that wsThresholdSize puts no limit on the total memory space available to workspaces that are currently in use. However, depending on the number of separate plot objects created by the application, smaller values will tend to reduce the total amount of space in use at a single time, at a cost of more frequent allocation and deallocation operations on these (potentially very large) memory spaces. The resource wsMaximumSize, on the other hand, specifies the maximum amount of memory the Workspace object allows before returning a fatal error. You can use this resource as a kind of brake that prevents runaway applications from using all the memory resources available in an environment.


Support functions

The Workspace object defines the following support function:
NhlGetWorkspaceObjectId
The NhlGetWorkspaceObjectId function returns the object id of the global Workspace object.

Status


See also