The OS/2 API Project

DosSubSetMem

PVOID pOffset (input)

This is the address of the memory pool used for suballocation.

ULONG ulFlags (input)

Flags used to describe the characteristics of the memory object being suballocated.

DOSSUB_INIT (0x00000001). This bit must be set for the memory block to be intialized for suballocation. If it is not set the request is to attach a process to a shared memory pool that was initialized by another process using DosSubSetMem.

DOSSUB_GROW (0x00000002). Setting this bit means that the size of the current memory_pool is to be increased. This will leave DOSSUB_INIT without meaning.

DOSSUB_SPARSE_OBJ (0x00000004). If a suballocation function is to be used to manage commitment of the pages in the memory pool this bit should be set. This means that all the pages of the memory block must be uncommitted. If this bit is not set the suballocation function will assume the pages to be committed and valid. If DosSubSetMem is used to increase the size of a memory pool, this bit must be the same as it was when the memory pool was originally initialized. If this is not the case an error will be returned.

DOSSUB_SERIALIZE (0x00000008). Setting this bit will serialize the memory pool.

The first DosSubSetMem request on a shared memory pool, it may be an init or a serialize request, will create the memory pool and open it for requesting processes. All following DosSubSetMem (serialize or attach) will attach the shared memory pool to the requested process.

ULONG ulSize (input)

The size in bytes of the memory pool. It's supposed to be a multiple of 8 bytes, if not it will be rounded down by the system.

APIRET rc

The following values can be returned

0	NO_ERROR
87	ERROR_INVALID_PARAMETER
310	ERROR_DOSSUB_SHRINK

The requester must begin by gaining access to the memory block in which the memory pool resides.

If you use DosSubSetMem, it should later be followed by DosSubUnsetMem to reset resources no longer needed.

The minimum size used with DosSubSetMem is 72 bytes. This since the memory pool contains 64 bytes of control information, and then you must add a multiple of 8 bytes for you to have memory to use.

Do NOT use DosSetMem to set or change the attributes of a page managed by the suballocation function. It can be done, but the result is unpredictable.

All pages in the memory pool should have the same attributes, and at least read/write access must have been requested for the pages when the memory was allocated.

DosSubSetMem( grow) is very closely related to memory and perfomance requirements of the requester.

If the requester needs the best possible performance for DosSubFreeMem, together with a guarantee that those requests will not fail due to lack of swap space, the requester should not use the sparse feature. This is because the suballocation function dynamically commit pages and request swap space for them. In this case the DosSubSetMem( grow) should be used to notify the suballocation function that more committed memory is available. Since, in most cases, this is not needed, they should instead allow the suballocation function to manage the pages in the memory pool and should initialize it with the sparse attribute set. In this case DosSubSetMem(grow) should have to be called.

Relevant Structures

Author

Additions

Last modified March 16/1996
Please send all errors, comments, and suggestions to: timur@vnet.ibm.com