__map_service() — Set memory mapping service

Standards

Standards / Extensions	C or C++	Dependencies
	both	POSIX(ON) OS/390 V2R9

Format

#define _OPEN_SYS_MAP_EXTENTION
#include <sys/mman.h>

int __map_service(struct _Mmg_service *parmlist, int count, *_Map_token_t);

General description

The __map_service() function is used to manipulate the map area created by the __map_init() function. The supported functions are defined under _Mmg_servicetype below.

Before calling the __map_service() service, the application should set values in the _Mmg_service structure as follows:

Element

Description

_Mmg_servicetype

Set the type of service being requested for each memory block defined in the array.

Request: Description
_Mmg_newblock: Set for an allocation of a new data block in the mapped area.
_Mmg_conn: Set to request that a data block be connected at the requested location in the map area.
_Mmg_disconn: Set to disconnect a data block from the map area.
_Mmg_free: Set to free the storage backing a data block.
_Mmg_cntl: Set to change the read or write permission settings for a data block.

_Mmg_serviceIflag

Used for _Mmg_cntl to indicate read or write and all other bits set to zero. For _Mmg_disconn to indicate if the backing storage is to be freed after disconnect. For _Mmg_newblock the option of _Mmg_NoConn can be set on to bypass the connect to the map area block. The token returned will have to be saved and used for connect services on a later call to make the block accessible. For all other _Mmg_serviceItype requests, set all the bits to zero.

_Mmg_serviceOflag

Used for status of the request. When the request has been successfully processed all the bits are set to zero. When processing an list of requests and a failure occurs in _Mmg_Reqfail is set on and further processing on the list is aborted. _Mmg_servicetype requests, set all the bits to zero.

_Mmg_token

This is returned as output for a _Mmg_newblock request and is used as input for _Mmg_conn, and _Mmg_free. It is ignored for _Mmg_disconn and _Mng_cntl.

_Mmg_res0b

Reserved, set to 0.

_Mmg_blkaddr

For _Mmg_newblock and _Mmg_conn this is input. It should be set to an address within the map area (on a block multiple) where you want to allocate a block or 0. If 0 is specified, the first available block in the map area is used. On output, this field contains the address within the map area that was assigned to the data block. For _Mmg_disconn it is input only and contains the address of the map block to be disconnected. For _Mng_cntl this field is required and specifies the block to be use for the _Mmg_cntl option. For _Mmg_free, _Mmg_cntl and _Mmg_newblock, when the option of _Mmg_NoConn is set on, this field is ignored.

With count reflecting the number of _Mmg_service structures included in the array structure supplied on parmlist parameter. With count a positive integer in the range of 1-1000.

With _Map_token_t the 8 character token retrieved from the _Mmg_token field in a _Mmg_service structure that returned successful from a __map_init() function call.

Usage notes

The __map_init and the __map_service functions are intended to be used in the following manner:
- The initial process calls __map_init to create a map area large enough for the biggest expected usage.
- The initial process forks worker processes which inherit the map area at the same virtual address. By having the map area at the same virtual address, storage blocks can be connected to the same block in map areas of different worker processes and pointers can be used to point to data in this or other blocks. This assumes they are always connected at the same location in the map area.
- As worker processes perform their tasks, they can request new blocks of storage to be created in the map area. Each block has a token associated with it. This token allows other worker processes to connect to the same block. In this respect, the map area acts like shared memory.
- The worker processes can connect as many blocks to their map area as will fit.
- When the worker process has no further need for a data block, it can disconnect it from the map area. After a delete request for a block, this block is actually freed when the last worker process disconnects for this block.
- When a worker process is completely done with a data block, the storage can be freed. This data is actually freed when the last worker process disconnects from that block.
- Using these services, the application could create multiple gigabytes of storage, of which only certain blocks are mapped into the worker processes at a given time.
- This service is designed to perform the storage connects and disconnects very fast. No data movement occurs.
- Storage blocks are initially connected in write mode. When a block is in write mode, all worker processes which have the block connected, have the block in write mode. If the block access is changed to read-only, then all worker processes which have the block connected, have the block in read-only mode.
- If the initial process or a worker process forks, then the child process inherits a map area initialized to the hidden state.
- Any areas within the map area which do not have a block connected are in the hidden state. Any reference to storage in the hidden state will trigger a SIGSEGV signal.

Returned value

If successful, __map_service() returns 0.

If unsuccessful, __map_service() returns -1 and sets errno to one of the following values:

Error Code

Description

EEXIST

A request was made to perform a service on a block but a map is not currently active in the process.

EFAULT

The parmlist (_Mmg_service structure) argument addresses either could not be accessed or was in read-only storage and could not be updated.

EINVAL

For one of the following reasons:

The block address provided is either not in the map area or it is not on a map block boundary.
A request was made to connect to a block or free the backing storage for a block but the token provided does not match that of any allocated block in the backing store.
A request was made to disconnect from a block but the block is not currently in the map area for this process.
A newblock or connect request was specified for a map area block that is already in use.
A request was made to connect to a block in the backing store that is currently marked to be freed. The connect is not permitted.
The count value was not a positive integer in the range of 1-1000.

ENOMEM