States

Returns

real

Return type

Number

Example

// Get the time of the current state
var time = GetTime();

// Get the time of the first state
var time = GetTime(1);

LockState(state_id[integer]) [static]

Description

"Locks" any memory already allocated for data storage in <state_id>, preventing it from being reused by other states looking for memory in which to store data.

When dealing with large models it is normally the case that the amount of data to be processed far exceeds the amount of memory installed in the computer, meaning that it is not possible to store all data of interest in memory at the same time. Therefore D3PLOT tries to minimise the amount of data currently stored in memory by reusing the memory allocated previously for other states and/or data components. This process is called "scavenging" and the rules it uses when trying to decide from where to scavenge memory are, in order of descending preference:

1. Data from a different component in a different state
2. Data from this component in a different state
3. Data from an unused component in this state
4. If none of the above are available then allocate some fresh memory from the operating system

In most cases a Javascript will be working with one state at a time, so the problem of reusing memory in this state for purpose A when it is still required for purpose B will not arise. However if, for example, you are writing a script that compares data from this state and the previous one inside a loop it is possible that "churning" could arise from the sequence:

.

For each state

GetData in state N Scavenges memory from state N-1 to store the data for state N

GetData in state N-1 Scavenges memory from state N to store data for state N-1

.

In this example the script would probably run incredibly slowly as each GetData() call would have to reread data from disk into the newly scavenged memory, so you would end up with <#elements * 2> disk reads of all the data for this component and element type. The same would be true if PutUbinData() or GetUbinData() were used as both of these require the data to be "put" or "got" to exist in memory, requiring that memory to be obtained from somewhere.

By "locking" states N and N-1 in this example you would force D3PLOT to allocate enough memory to hold both data vectors in memory at the same time, and the script would run <#elements * 2> times faster. For a model with 1,000,000 elements this might reduce the run-time from months to seconds!

Clearly states should not be "locked" unnecessarily or, more importantly, left "locked" when there is no longer any need for the data they contain, since this will lead to a significant build-up of memory usage. Therefore states can be unlocked in three ways:

• Explicitly by using the Javascript function UnlockState()
• Implicitly by using the Javascript function SetCurrentState(), which unlocks all states except the current one
• Implicitly by exiting the Javascript, as normal (interactive or batch) D3PLOT usage will implicitly unlock all but the current state.

To summarise: this function is likely to be needed only when you are performing repeated "gets" and/or "puts" of data to and from more than one state.

Locking and unlocking states takes place in the current model only, and has no effect on states in any other model.

Returns

boolean

Return type

Boolean

Example

// Lock data in state #13
LockState(13);

SetCurrentState(state_id[integer]) [static]

Description

Sets the current state for the JavaScript interface to state_id

This is the state used for all the "get" and "put" functions which handle model-related data. If the optional state_id argument in a get/put function call is used then that state is used instead for the duration of that call, but this current state is not changed.

The current state is a property of the current model, in other words each model has its own, separate, current state. For all models this defaults to state #1 (if present).

Setting the current state in model i has no effect on the current state in any other model.

Returns

boolean

Return type

Boolean

Example

// Make state #27 current
SetCurrentState(27);

UnlockState(state_id[integer]) [static]

Description

"Unlocks" this state for the purposes of memory scavenging, making any data vectors within it eligible for reuse by other states looking for memory

Please see the documentation on LockState() for a description of what this function does and when it might be needed.

Returns

boolean

Return type

Boolean

Example

// Unlock data in state #13
UnlockState(13);