MC
API

Subsystem
list

Top
level

Memory Utilities

This is a proposal for a set of utilities for querying and manipulating the amount of free memory that is available to the Application.

Running Scripts with Low Memory

You can run scripts with the application in a low-memory condition by setting the value of giRECmaxFreeMem (in MClocal.inc) to a non-zero value. At the start of each script, the recovery system (i.e. ScriptEnter) will check the application to see how much free memory it has. If the application has more than the amount specified by giRECmaxFreeMem, the recovery system will "steal" memory from the application to reduce its free memory to the specified amount.

Note that this only happens at the beginning of each script, not at the beginning of each testcase.

If giRECmaxFreeMem is set to zero, recovery system will not perform this check.

Ensuring Sufficient Memory

You can ensure that the application has sufficient memory for each testcase by setting the value of giRECminFreeMem to a non-zero value. At the start of each script and each testcase, the recovery system (i.e. ScriptEnter and TestcaseEnter) will check the application to see how much free memory it has. If the application has less than the amount specified by giRECminFreeMem, then the recovery system will raise an exception.

In your script you can change the minimum free memory parameter by calling RECsetMinFreeMem.

If giRECminFreeMem is set to zero, recovery system will not perform this check.

Manipulating Free Memory In a Script

In your test script you can query or change the amount of free memory available to the application by using MEMgetFree, MEMsteal and MEMreturn.

API Summary

Types

MEMblockID - identifies a block of stolen memory

Utility Routines

`integer`	`MEMgetFree`	`()`
`MEMblockID`	`MEMsteal`	`(integer iNumBytes)`
`void`	`MEMreturn`	`(MEMblockID)`

Recovery System Routines

`void`	`RECsetMinFreeMem`	`(integer iNumBytes)`
`integer`	`RECgetMinFreeMem`	`()`

New MClocal.inc Variables

giRECmaxFreeMem - maximum free memory at start of script
giRECminFreeMem - minimum free memory at start of testcase

The RECblockID Type

This is a data type whose value identifies a block of memory "stolen" from the application by MEMsteal. You can only obtain legal values of this type from MEMsteal, and the only legal use of a value of this type is to pass it to MEMreturn.

Declaration

type RECblockID is /* implementation is private! */

MEMgetFree

Returns the number of bytes of free memory in the application. Note that this function is defined somewhat differently from the built-in QAP function SYS_GetFreeMemory. In particular, the QAP function cannot be used on UNIX.

Declaration

integer MEMgetFree ( )

Inputs

None.

Outputs

Returns: The number of bytes of free memory in the application.

MEMsteal

This routine reduces the amount of free memory in the application by "stealing" (allocating) a block of memory. You can return the stolen memory by calling MEMreturn.

Declaration

MEMblockID MEMreturn 
			(integer iNumBytes)

Inputs

iNumBytes: The number of bytes to steal from the application.

Outputs

Returns: A value that identifies the stolen memory block so that you can return it to the application.

Exceptions

X_MEM_INSUFFICIENT_MEMORY

MEMreturn

Returns to the application a block of memory that was stolen by MEMsteal. Note that you can only return a block once; returning it twice is a programming error and will cause an exception to be raised.

Declaration

void MEMreturn (MEMblockID uBlockID)

Inputs

uBlockID: A value that identifies the block of memory to be returned. This value must be obtained from MEMsteal.

Outputs

None.

Exceptions

X_MEM_BOGUS_BLOCK

RECsetMinFreeMem

Note: this routine will be part of the recovery system.

Sets the minimum allowable amount of application free memory. If this is set to a non-zero value, the recovery system will check the application at the start of each script and each testcase to see how much free memory it has. If the application has less than the specified amount, then the recovery system will raise an exception.

If this parameter is set to zero, recovery system will not perform this check.

The initial value of this parameter is specified by the variable giRECminFreeMem.

Declaration

void RECsetMinMem (integer iNumBytes)

Inputs

iNumBytes: The minimum allowable number of bytes of free memory. This value must not be less than zero.

Outputs

None.

RECgetMinFreeMem

Note: this routine will be part of the recovery system.

Returns the current minimum allowable amount of free memory, as set by the most recent call to RECsetMinFreeMem.

Declaration

integer RECgetMinFreeMem ();

Inputs

None.

Outputs

Returns: The minimum allowable number of bytes of free memory.

This page is maintained by (REMOVED).

Last updated 26 October 1996.