Macro | Brief description |
CSTAT | Changes the status of memory pages of a program (paging and read/write access) |
CSTMP | Changes the read/write access to a memory pool |
DISMP | Terminates participation in a memory pool. The specified memory pool is deallocated |
ENAMP | Sets up a memory pool, or enables participation in an existing memory pool |
MINF | Provides information about allocation of pages and the size of a memory pool |
RELMP | Releases (contiguous) memory space within a memory pool |
REQMP | Requests (contiguous) memory space within a memory pool |
SHOWMP | Outputs information on Common Memeory Pools which are currently created in the |
Memory pool characteristics
A memory pool is an area in memory (class 6 memory) that can be shared by several users. Each of the participating users may read from or write to any page of the pool. A user who is not a participant has no access to the pool pages.
If a pool participant changes the contents or the status of the pool pages, all pool participants are affected. If a participant writes to a page of the pool, this data is available to all other participants. If a participant protects a pool page against overwriting (CSTAT macro), no pool participant can write to this page any more. Subroutines residing in the pool should be reentrant.
In order to coordinate accesses to the memory pool and to ensure efficient interworking, execution of the participating tasks should be synchronized. One way in which the user may accomplish this is by the (task) serialization method (see "(Task) serialization").
Information on the memory pools currently created in the system and the joined tasks is provided by the SHOWMP macro and the BS2000 command /SHOW-MEMORY-POOL-STATUS, see the “Commands” manual [19 (Related publications)].
Opening a memory pool
By means of the ENAMP macro, a user can set up a new memory pool or join an existing one (dependent on the MODE operand of the macro).
When creating a new pool, the user defines its name, scope and size. These definitions are binding for any further participants. The scope determines whether (and if so, which) other tasks may participate in the pool.
The size of the pool is limited by the amount of user memory available to the participants. The memory pool is created in units of 64K or 1 Mb. Memory pools with 64K units are always created below the 16-Mb boundary and will not be supported on a long-term basis. It is advisable to create memory pools with 1-Mb units only (enhanced performance). The ENAMP macro causes the system to reserve for the pool the appropriate number of entries in the segment table (see figure 6).
A user joining an existing memory pool must accept the pool name, scope and size. The system provides an ID that can be used instead of the name to speed up processing. When opening a pool, each participant can specify an address at which the system can enter the ID.
When opening a pool, users may individually specify which part of their available address space is to be allocated to the memory pool by specifying a start address for the pool within this address space. Each participant may address the pool using a selected area of the address space. The same address need not be selected by all participants. The system supplies the participants with the virtual address of the first pool byte via register R1.
Closing a memory pool
The DISMP macro terminates the user's participation in the specified memory pool, thereby releasing that part of that user's address space that was allocated to the pool. If DISMP is called by the last remaining or the sole pool participant, the memory pool is deleted altogether. (The participant deleting the memory pool need not be identical with the participant who created the pool.)
Requesting memory in a memory pool
Using the REQMP macro, any participant in a memory pool can request memory in the pool in 4K pages. The system allocates the requested pages in the virtual memory area reserved for the pool (by ENAMP). Any pool participant can now write to and read from the allocated pages. The participant who submits the request (binding for all participants) specifies which, and how many, pages are to be allocated within the reserved pool area. The MINF macro provides information on the page allocation and size of the memory pool.
Releasing memory in a memory pool
Using the RELMP macro, any participant in a memory pool can release memory pages previously allocated to the memory pool. It is irrelevant which participant originally reserved the memory area and which portions of it were allocated. The participant that calls RELMP specifies how many and which of the allocated pages are to be released. The release is valid for all pool participants.
Page status in a memory pool
The ENAMP macro may be used to specify whether the memory area is to be resident. This may only be done by an authorized caller: the START-PROGRAM command for the program calling ENAMP must define the number of resident pages for the task. This value must be taken into account if the user defines the size of the memory pool in the ENAMP call and also specifies that the pool is to be resident.
Using the CSTAT macro, a pool participant can change the page status within user
memory. The page status of a memory pool can be changed by means of CSTAT from pageable to resident only. A change in page status from resident to pageable is ignored for memory pools, which have been specified as resident by ENAMP.
The CSTAT macro is not restricted by memory pool boundaries. The range of pages influenced by CSTAT may begin outside of a pool and end within the pool, and vice versa. When the page status is changed from resident to pageable, only pages outside the resident memory pool are changed.
If the page status is changed from pageable to resident, all pool participants can access the resident pages. This change of status can only be performed by an authorized pool participant. (The START-PROGRAM command for the program calling CSTAT specifies whether and how many memory pages may be resident).
The user can also use CSTAT to set the access mode (read/write access) for the specified memory pages. The memory pages can be inside or outside a memory pool.
The (authorized) user can set the access mode for a memory pool with the CSTMP macro. This specification always applies to all pages of the memory pool. The following points should be noted:
CSTAT has a lower priority than CSTMP for changing the access mode (read/write access).
Write protection imposed with CSTMP cannot be removed with CSTAT.CSTAT is rejected if write protection was imposed with CSTMP.
Write protection imposed with CSTAT can be extended to all pool pages with CSTMP.
Restrictions on the use of memory pools
Checkpoint processing (WRCPT macro / RESTART-PROGRAM command) is illegal if a memory pool is open.
The HOLD-TASK command (see “Commands” manual [19 (Related publications)]) is rejected.
If an unrecoverable main memory error occurs in a pool page, any program which attempts to access the errored pool page will be terminated.
Figure 6: Establishing a connection to and accessing a memory pool page (/390 servers)
(1) | The ENAMP macro establishes a connection with the memory pool AB. |
(2) | The real start address of the memory pool page table is entered in the next free entry of the segment table. In this case, the next free entry is the entry for the third segment. For user 1, therefore, memory pool AB starts at the virtual address X'00200000'. This virtual start address is stored in register R1. |
(3) | The contents of register R1 are loaded into register R5. Both registers now contain the virtual start address of memory pool AB for user 1. |
(4) | 5 pages (X'5000') are added to the virtual start address of memory pool AB and the results are stored in register R5. |
(5) | The REQMP macro then requests the 6th page of memory pool AB. |
(6) | The 6th entry in the memory pool page table contains the real frame number of the 6th page of memory pool AB in main memory. The 6th entry in the page table extension contains the logical block number of the 6th page in page memory. |
(7) | The 6th page of memory pool AB is accessed. |