DosSubSetMem

From EDM2
Jump to: navigation, search

DosSubSetMem is used to initialize a pool for suballocation, or used to increase the size of an already initialized memory pool.

Syntax

DosSubSetMem( pOffset, ulFlags, ulSize )

Parameters

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.

Returns

APIRET rc

The following values can be returned:

0 NO_ERROR
87 ERROR_INVALID_PARAMETER
310 ERROR_DOSSUB_SHRINK
{{{v3}}} {{{w3}}}


Usage Explanation

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.

Sample Code

#define INCL_DOSMEMMGR
#include <os2.h>
#include <bsememf.h>

PVOID Offset;	/* The address of the memory pool used for suballocation. */
ULONG Flags;	/* Flags describing the memory object which we */
		/* suballocate.                                */
ULONG Size;	/* Size in bytes of the memory pool. */
APIRET rc;	/* Just to take care of the return code. */

Size = 40000;	/* The memory pool has a size of 40000 bytes. This is    */
		/* already a multiple of 8 bytes, so no rounding down is */
		/* made by the system.                                   */
Flags = DOSSUB_INIT | DOSSUB_SPARSE_OBJ;
		/* The memory pool should be initialized and memory    */
		/* commitment should be taken care of by the following */
		/* DosSubAllocMem calls.                               */
rc = DosSubSetMem( Offset, Flags, Size);

if (rc != 0)
{
   /* We have an error we must take care of. */
}

See Also