Virtual Memory: 3.11 Using Virtual Memory: File-Access Synchronization

VMGrabExclusive(), VMReleaseExclusive()

Sometimes several different geodes will need access to the same VM file. Generally, these will be several different copies of the same application, perhaps running on different machines on a network. GEOS provides three different ways shared-access can be handled.

A VM file can be one of three different types: standard, "public," and "shared-multiple." By default, all new VM files are standard. The file's type is one of its extended attributes, and can be changed with the routine FileSetHandleExtendedAttributes() (see the File System chapter). The document control automatically lets the user select what kind of file to create, and changes its type accordingly. (See the Document Objects chapter.)

Only one geode may write to a standard GEOS VM file at a time. If a geode has the file open for read/write access, no other geode will be allowed to open that file. If a geode has the file open for read-only access, other geodes are allowed to open it for read-only access, but not for read-write access. If a file is opened for read-only access, blocks cannot be dirtied or updated. If a geode tries to open a file for writing when the file is already open, or if the geode tries to open it for reading when the file has already been opened for writing, VMOpen() will return an error.

In general, when a file is opened, it is by default opened for read-write access. For example, the document control objects present a dialog box which lets the file be opened for read-only access, but has this option initially turned off. However, some files are used mainly for reference and are infrequently changed. For example, a company might keep a client address book on a network drive. Most of the time, people would just read this file; the file would only occasionally be changed. For this reason, GEOS lets you declare VM file as "public." Public files are, by default, opened for read-only access. In all other respects the file is the same as a standard GEOS VM file; it can be opened by several readers at a time, but by only one geode at a time if the geode will be writing.

Sometimes several geodes will need to be able to write to a file at once. For example, a company might have a large customer database, and several users might be writing records to the database at the same time. For this reason, GEOS lets you create "shared-multiple" files. Several geodes can have a "shared-multiple" file open at once. However, a geode cannot access the file whenever it wants. Instead, it must get the file's semaphore to access the file's data. When it needs to access the file, it calls VMGrabExclusive() . This routine takes four arguments:

The handle of the VM file
A timeout value
If a timeout value is passed, VMGrabExclusive() will give up trying to get the semaphore after a specified number of seconds has passed. If a timeout value of zero is passed, VMGrabExclusive() will block until it can get the file's semaphore.
A member of the VMOperation enumerated type
This specifies the kind of operation to be performed on the locked file. The VMOperation values are described below.
A pointer to a word-length variable.
If this call to VMGrabExclusive() fails and times out, the operation currently being performed will be written here.

The routine returns a member of the VMStartExclusiveReturnValue enumerated type. The following return values are possible:

VMSERV_NO_CHANGES: No other thread has changed this file since the last time this thread had access to the file.
VMSERV_CHANGES: The file may have been altered since the last time this thread had access to it; the thread should take appropriate actions (such as re-reading any cached data).
VMSERV_TIMEOUT: This call to VMGrabExclusive() failed and timed out without getting access to the file.

When a geode calls VMGrabExclusive() , it must pass a member of the VMOperation enumerated type. Most of the values are used internally by the system; while a geode should never pass these values, they may be returned by VMGrabExclusive() if the call times out. The following values are defined in vm.h :

VMO_READ: This indicates that the geode will not change the file during this access. This lets the kernel perform some optimizations.
VMO_INTERNAL
VMO_SAVE
VMO_SAVE_AS
VMO_REVERT
VMO_UPDATE: These values are set only by the kernel. Applications should never pass them.
VMO_WRITE: This indicates that the geode may write to the file during this access.

The application may also pass any value between VMO_FIRST_APP_CODE and 0xffff. The kernel treats all these values as synonymous with VMO_WRITE; however, the application may choose to associate meanings with numbers in this range (perhaps by defining an enumerated type whose starting value is VMO_FIRST_APP_CODE).

When a thread is done accessing a file, it should release its exclusive access by calling VMReleaseExclusive() . The routine takes one argument, namely the file handle. It does not return anything.

GEOS SDK TechDocs |

3.10 The VM File's Map Block | Next:

3.12 Other VM Utilities