Memory objects

Programs obtain storage above the bar in chunks of virtual storage called memory objects. The system allocates a memory object as a number of virtual segments; each segment is a megabyte in size and begins on a megabyte boundary. A memory object can be as large as the memory limits set by your installation and as small as one megabyte.

Using the IARV64 macro, a program can create and free a memory object and manage the physical frames that back the virtual storage. You can think of IARV64 as the GETMAIN/FREEMAIN or STORAGE macro for virtual storage above the bar. (GETMAIN/FREEMAIN and STORAGE do not work on virtual storage above the bar; neither do CPOOL or callable cell pool services.)

When a program creates a memory object, it provides an area in which the system returns the memory object's low address. You can think of that address as the name of the memory object. After creating the memory object, the program can use the storage in the memory object much as it used storage in the 2-gigabyte address space; see Using a memory object. The program cannot safely operate on storage areas that span more than one memory object.

To help the system manage the physical pages that back ranges of addresses in memory objects, a program can alert the system to its use of some of those pages, making them available for the system to steal and then return.

The program can free the physical pages that back ranges of memory objects and, optionally, clear those ranges to zeros. Later, the program can ask the system to return the physical backing from auxiliary storage. When it no longer needs the memory object, the program frees it in its entirety.

While your program can obtain only one memory object at a single invocation of IARV64, it can, for management purposes, relate a set of two or more memory objects to each other by specifying a user token, a value you choose. A program can then delete all memory objects that have the same user token value.