Document revision date: 19 July 1999

To see the C function prototypes for the services described in these chapters, enter the following command:

$ library/extract=starlet sys$library:sys$starlet_c.tlb/output=filename

Then search the output file for the service you want to see.

One of the major features of the Galaxy platform is the ability to share resources across multiple instances of the operating system. As with any shared resource, the need arises to synchronize access to that resource. The services described in this chapter provide primitives upon which a cooperative scheme can be created to synchronize access to shared resources within a Galaxy.

A galaxy lock is a combination of a spinlock and a mutex. While attempting to acquire an owned galaxy lock, the thread will spin for a short period. If the lock does not become available during the spin, the thread will put itself into a wait state. This is different from SMP spinlocks in which the system crashes if the spin times out, behavior that is not acceptable in a Galaxy.

Given the nature of galaxy locks, they will reside somewhere in shared memory. That shared memory can be allocated either by the user or by the galaxy locking services. If the user allocates the memory, the locking services track only the location of the locks. If the locking services allocate the memory, it is managed on behalf of the user.

Unlike other monitoring code which is only part of the MON version of execlets, the galaxy lock monitoring code is always loaded.

There are several routines provided to manipulate galaxy locks. The routines do not provide anything but the basics when it comes to locking. They are a little richer than the spinlocks used to support SMP, but far less than what the lock manager provides.

Acquires ownership of an OpenVMS Galaxy lock.

Format

SYS$ACQUIRE_GALAXY_LOCK handle ,timeout ,flags

C Prototype

int sys$acquire_galaxy_lock (unsigned __int64 lock_handle, unsigned int timeout, unsigned int flags);

Arguments

handle

OpenVMS usage	galaxy lock handle
type	quadword (unsigned)
access	read
mechanism	input by value

The 64-bit lock handle that identifies the lock to be acquired. This value is returned by SYS$CREATE_GALAXY_LOCK.

timeout

OpenVMS usage	wait timeout
type	longword (unsigned)
access	read
mechanism	input by value

The 32-bit wait or spin timeout specified in 10 microsecond units. If not specified, defaults to 10 microseconds.

flags

OpenVMS usage	bit mask
type	longword (unsigned)
access	read
mechanism	input by value

Control flags defined by the GLOCKDEF macro: GLOCK$C_NOBREAK, GLOCK$C_NOSPIN, and GLOCK$C_NOWAIT.

Description

This service is used to acquire ownership of an OpenVMS Galaxy lock. If the lock is free, the caller becomes the owner and control returns immediately. If the lock is owned, based on the input flags and the timeout value, either the caller will wait or an error will be returned.

The default behavior when an attempt is made to acquire a lock that is owned, is to spin for 10 microseconds and then to wait. If a wait timeout value was specified in the call, it is used. Otherwise, the timeout value set in the lock by $CREATE_GALAXY_LOCK will be used. This behavior can be changed with the input flags.

If just GLOCK$C_NOSPIN is specified and the lock is owned, no spin will be done.

If just GLOCK$C_NOWAIT is specified and the lock is owned, the caller will only spin on the lock. If a timeout value is specified in the call, it is used as the spin time. Otherwise, the caller will spin for 10 microseconds. If the lock does not become available during the spin, the lock is not acquired and SS$_NOWAIT is returned.

If both GLOCK$C_NOSPIN and GLOCK$C_NOWAIT are specified and the lock is owned, control returns immediately. The lock is not acquired and SS$_NOWAIT is returned.

Due to system events such as OpenVMS Galaxy instance shutting down, a lock may become owned by a nonexistent entity. If this occurs, the default behavior of $ACQUIRE_GALAXY_LOCK is to break the old lock ownership. The caller becomes the new owner and the service returns SS$_BROKEN. If GLOCK$C_NOBREAK is specified, $ACQUIRE_GALAXY_LOCK will not break the lock ownership and returns SS$_NOBREAK.

Required Access or Privileges

Write access to OpenVMS Galaxy lock table contains lock to acquire.

Required Quota

None

Related Services

$CREATE_GALAXY_LOCK, $CREATE_GALAXY_LOCK_TABLE, $DELETE_GALAXY_LOCK, $DELETE_GALAXY_LOCK_TABLE, $GET_GALAXY_LOCK_INFO, $GET_GALAXY_LOCK_SIZE, $RELEASE_GALAXY_LOCK

Return Values

SS$_NORMAL	Normal completion.
SS$_BADPARAM	Bad parameter value.
SS$_BROKEN	Lock acquired after lock ownership was broken.
SS$_IVLOCKID	Invalid lock ID.
SS$_IVLOCKOP	Invalid lock operation.
SS$_IVLOCKTBL	Invalid lock table.
SS$_LOCK_TIMEOUT	Failed to acquire lock; request has timed out.
SS$_NOBREAK	Failed to acquire lock; lock ownership is broken.
SS$_NOWAIT	Failed to acquire lock; NOWAIT was specified.

Allocates an OpenVMS Galaxy lock block from a lock table created with the $CREATE_GALAXY_LOCK_TABLE service.

Format

SYS$CREATE_GALAXY_LOCK lcktbl_handle ,name ,timeout ,size ,ipl ,rank ,handle

C Prototype

int sys$create_galaxy_lock (unsigned int lcktbl_handle, char *name, unsigned int size, unsigned int timeout, unsigned int ipl, unsigned int rank, unsigned __int64 *lock_handle);

Arguments

lcktbl_handle

OpenVMS usage	lock table handle
type	longword (unsigned)
access	read
mechanism	input by value

The 32-bit lock table handle that identifies the lock table in which to create the lock. This value is returned by SYS$CREATE_GALAXY_LOCK_TABLE.

name

OpenVMS usage	address
type	zero-terminated string
access	read
mechanism	input by reference

The name parameter is a pointer to a zero-terminated string. The name can be a maximum of 15 characters. Lock names are not checked for uniqueness; therefore, multiple locks can be created with the same name.

timeout

OpenVMS usage	wait timeout
type	longword (unsigned)
access	read
mechanism	input by value

The 32-bit wait or spin timeout specified in 10 microsecond units. If not specified, the timeout defaults to 10 microseconds.

size

OpenVMS usage	byte count
type	longword (unsigned)
access	read
mechanism	input by value

The size of the galaxy lock in bytes. Galaxy locks have two legal sizes. These values are returned by SYS$GET_GALAXY_LOCK_SIZE. The value passed to SYS$CREATE_GALAXY_LOCK must be equal to the value passed to the call to SYS$CREATE_GALAXY_LOCK_TABLE.

ipl

OpenVMS usage	IPL of lock
type	longword (unsigned)
access	read
mechanism	input by value

For galaxy locks acquired in kernel mode, the IPL to raise to while the lock is held. This parameter is ignored for all other access mode.

rank

OpenVMS usage	rank of lock
type	longword (unsigned)
access	read
mechanism	input by value

Rank applied to a galaxy lock. Ranking is used to detect potential deadlocks. This parameter is currently ignored.

handle

OpenVMS usage	address
type	quadword (unsigned)
access	write
mechanism	output by reference

The handle parameter is a pointer to a quadword. The value returned is a 64-bit handle that uniquely identifies the lock galaxy-wide.

Description

This service allocates an OpenVMS Galaxy lock block from a lock table created with the $CREATE_GALAXY_LOCK_TABLE service.

Required Access or Privileges

For System Lock: CMKRNL, SHMEM
For User Lock: SHMEM
Write access to Lock Table

Required Quota

None

Related Services

$ACQUIRE_GALAXY_LOCK, $CREATE_GALAXY_LOCK_TABLE, $DELETE_GALAXY_LOCK, $DELETE_GALAXY_LOCK_TABLE, $GET_GALAXY_LOCK_INFO, $GET_GALAXY_LOCK_SIZE, $RELEASE_GALAXY_LOCK

Return Values

SS$_NORMAL	Normal completion.
SS$_ACCVIO	Access violation on parameter.
SS$_BADLCKTBL	OpenVMS Galaxy lock table is corrupt.
SS$_BADPARAM	Bad parameter value.
SS$_IVLOCKID	Invalid lock ID.
SS$_IVLOCKTBL	Invalid lock table.
SS$_INSFMEM	Insufficient memory in lock table.
SS$_NOCMKRNL	Operation requires CMKRNL privilege.
SS$_NOSHMEM	Operation requires SHMEM privilege.

Allocates an OpenVMS Galaxy lock table.

Format

SYS$CREATE_GALAXY_LOCK_TABLE name ,accmode ,section_size ,section_type ,prot ,lock_size ,lcktbl_handle

C Prototype

int sys$create_galaxy_lock_table (char *name, unsigned int accmode, unsigned __int64 section_size, unsigned int section_type, unsigned int prot, unsigned int lock_size, unsigned int *lcktbl_handle);

Arguments

name

OpenVMS usage	address
type	zero-terminated string
access	read
mechanism	input by reference

The name parameter is a pointer to a zero-terminated string. The name is given to the global section that is created to contain the galaxy locks.

accmode

OpenVMS usage	access mode
type	longword (unsigned)
access	read
mechanism	input by value

Access mode that is to be the owner of the pages created during the mapping. The accmode argument is a longword containing the access mode.

The $PSLDEF macro defines the following symbols for the four access modes:

Symbol	Access Mode
PSL$C_KERNEL	Kernel
PSL$C_EXEC	Executive
PSL$C_SUPER	Supervisor
PSL$C_USER	User

The most privileged access mode used is the access mode of the caller.

section_size

OpenVMS usage	byte count
type	quadword (unsigned)
access	read
mechanism	input by value

Length of the global section to be created, in bytes. The size must be specified as a multiple of the CPU-specific page size. A size of zero is illegal.

section_type

OpenVMS usage	bit mask
type	longword (unsigned)
access	read
mechanism	input by value

Used to control where in virtual memory the global section is created. If GLCKTBL$C_PROCESS is specified, the section is created in P2 (process) space. If GLCKTBL$C_SYSTEM is specified, the section is created in S0/S1 (system) space. These constants are defined in the GLOCKDEF macro.

prot

OpenVMS usage	protection
type	longword (unsigned)
access	read
mechanism	input by value

Protection to be applied to the global section.

The mask contains four 4-bit fields. Bits are read from right to left in each field.

Cleared bits indicate that read, write, execute, and delete access, in that order, are granted to the particular category of user.

Only read and write access are meaningful for lock section protection. Delete access bits are ignored.

lock_size

OpenVMS usage	byte count
type	longword (unsigned)
access	read
mechanism	input by value

The size of the galaxy lock in bytes. Galaxy locks have two sizes. The legal values are returned by SYS$GET_GALAXY_LOCK_SIZE.

lcktbl_handle

OpenVMS usage	address
type	longword
access	write
mechanism	output by reference

Pointer to a longword. The value returned is a 32-bit handle that uniquely identifies the lock table galaxy-wide.

Description

This service allocates an OpenVMS Galaxy lock table. This structure is used to maintain information about a shared memory section, which this service also creates. The first caller of the service with a unique lock table name creates the section. Additional callers map it. This shared memory section contains a set of Galaxy locks. All locks residing in the section are of the same size. Once the lock table is created, the $CREATE_GALAXY_LOCK service can be used to create and allocate a lock from the table.

The flags GLCKTBL$C_PROCESS and GLCKTBL$C_SYSTEM specify whether the shared memory region is mapped into system space or process space. Creation of process space sections requires the SHMEM privilege. Creation of system space sections requires the SHMEM and CMKRNL privileges.

Required Access or Privileges

CMKRNL, SHMEM

Required Quota

None

Related Services

$ACQUIRE_GALAXY_LOCK, $CREATE_GALAXY_LOCK, $DELETE_GALAXY_LOCK, $DELETE_GALAXY_LOCK_TABLE, $GET_GALAXY_LOCK_INFO, $GET_GALAXY_LOCK_SIZE, $RELEASE_GALAXY_LOCK

Return Values

SS$_NORMAL	Normal completion.
SS$_ACCVIO	Access violation on parameter.
SS$_BADPARAM	Bad parameter value.
SS$_CREATED	File or section did not exist; has been created.
SS$_IVLOCKID	Invalid lock ID.
SS$_NOPRIV	No privilege for attempted operation.
SS$_NOCMKRNL	Operation requires CMKRNL privilege.
SS$_NOSHMEM	Operation requires SHMEM privilege.

Invalidates an OpenVMS Galaxy lock and deletes it.

Format

SYS$DELETE_GALAXY_LOCK handle

C Prototype

int sys$delete_galaxy_lock (unsigned __int64 lock_handle);

Arguments

handle

OpenVMS usage	galaxy lock handle
type	quadword (unsigned)
access	read
mechanism	input by value

The 64-bit lock handle that identifies the lock to be deleted. This value is returned by SYS$CREATE_GALAXY_LOCK.

Description

This service invalidates the OpenVMS Galaxy lock and deletes it. The memory for the lock is not truly deleted; however, it is put on a free list for later use.

Required Access or Privileges

CMKRNL, SHMEM

Required Quota

None

Related Services

$ACQUIRE_GALAXY_LOCK, $CREATE_GALAXY_LOCK, $CREATE_GALAXY_LOCK_TABLE, $DELETE_GALAXY_LOCK_TABLE, $GET_GALAXY_LOCK_INFO, $GET_GALAXY_LOCK_SIZE, $RELEASE_GALAXY_LOCK

Return Values

SS$_NORMAL	Normal completion.
SS$_BADLCKTBL	Galaxy lock table is corrupt.
SS$_IVLOCKID	Invalid lock ID.
SS$_IVLOCKTBL	Invalid lock table.
SS$_LOCKINUSE	Invalid operation; lock is in use.
SS$_NOCMKRNL	Operation requires CMKRNL privilege.
SS$_NOSHMEN	Operation requires SHMEM privilege.

	privacy and legal statement
6512PRO_010.HTML