Virtual Memory: 3.4 Using Virtual Memory: Creating and Freeing Blocks

VMAlloc(), VMAllocLMem(), VMFree()

Once you have created a VM file, you have to allocate blocks in order to write data to the file. The usual way to do this is with VMAlloc() . This routine takes three word-sized arguments:

The file handle
This argument is overridden if a default VM file is set.
A user-ID number
This can be any word of data the application wants to associate with the VM block. The application can locate blocks with a given user ID by using VMFind() (see You can locate VM blocks by their user ID numbers. The routine VMFind() takes three arguments: the VM file handle, a VM block handle, and the user ID for which to look. The routine looks through the block table, starting with the handle after th ).
The number of bytes in the block
This may be zero, in which case no memory is allocated; a memory block must be specifically attached with VMAttach() (see Attaching Memory Blocks ).

The routine returns the handle of the VM block. Before you can use the block, you have to lock it with VMLock() . The block is marked dirty when it is allocated.

There is a routine to allocate a block and initialize it as an LMem heap. This is useful if you are storing object blocks in a VM file. The routine, VMAllocLMem() , takes three arguments:

The VM file handle
This is overridden if a default VM file is set.
A member of the LMemTypes enumerated type
This specifies what kind of heap the LMem heap will be. (See the Local Memory chapter.)
The size of the block header
Use this if you want to store extra data in the LMem block header. To use the standard LMem header, pass an argument of zero. (See the Local Memory chapter.)

The routine creates a VM block and allocates a global memory block to go with it. It initializes the heap in the global block and marks the block as dirty. The LMem heap will begin with two LMem handles and a 64-byte heap; this will grow as necessary. The VM block will have a user ID of zero; you can change this if you wish. The routine returns the handle of the new VM block.

There are two other ways to create LMem blocks in a VM file; these ways give you more control of the block's initialization. You can allocate a VM block normally, lock that block, then get the handle of the associated memory block and initialize an LMem heap in it; or you can allocate an LMem heap normally, and attach that memory block to the VM file using VMAttach() . For more details on LMem heaps, see the Local Memory chapter.

To free a VM block, call VMFree() . This routine is passed two arguments: the VM file handle, and the VM block handle. The handle will immediately be freed, even if it is locked. Any associated memory will also be freed. If you want to keep the memory, detach the global memory block from the file (with VMDetach() ) before you free the block.

GEOS SDK TechDocs |

3.3 Changing VM File Attributes | Next:

3.5 Attaching Memory Blocks