Updated: 11 December 1998

OpenVMS Alpha Galaxy Guide

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.

14.1 SYS$CREATE_GALAXY_LOCK_TABLE

This service allocates a galaxy locktable structure. This structure is used to maintain information about the shared memory section, which this service also creates. The first caller of the service with a unique locktable 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 locktable is created, the SYS$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.

sys$create_galaxy_lock_table(name, accmode, section_size, section_type, prot, lock_size, handle)

parameter	size (bytes)	type	usage
name	8	input by value	address of the lock table name (ASCIZ)
accmode	4	input by value	access mode of the lock table
section size	8	input by value	virtual size of lock section
section type	4	input by value	glcktbl$c_process or glcktbl$c_system
prot	4	input by value	protection applied to lock section
lock_size	4	input by value	size of the galaxy locks in the section
handle	8	output by ref	lock table handle

Return status:

• SS$_ACCVIO
• SS$_BADPARAM
• SS$_CREATED
• SS$_IVLOCKID
• SS$_NOPRIV
• SS$_NOSHMEM
• SS$_NORMAL
• Any status from the shared memory support routines

This service deletes a galaxy lock table. If there are no longer any mappers of the locktable section, which the table maintains, it is deleted.

sys$delete_galaxy_lock_table (handle)

parameter	size (bytes)	type	usage
handle	8	input by value	lock table handle

Return status:

• SS$_BADPARAM
• SS$_IVLOCKID
• SS$_IVLOCKTBL
• SS$_NOPRIV
• SS$_NOSHMEM
• SS$_NORMAL

This service sets a galaxy lock to a state considered to be invalid by the SYS$ACQUIRE_GALAXY_LOCK service. This routine is intended to be used only on locks which reside in shared memory allocated by the user and initialized with SYS$INIT_GALAXY_LOCK.

sys$reset_lock(handle, va)

parameter	size (bytes)	type	usage
handle	8	input by value	galaxy lock handle
va	8	input by ref	address of galaxy lock

Return status:

• SS$_BADLCKTBL
• SS$_IVLOCKID
• SS$_LOCKINUSE
• SS$_NORMAL

This services allocates a galaxy lock block from a locktable created with the SYS$CREATE_GALAXY_LOCK_TABLE service. It then uses SYS$INIT_GALAXY_LOCK to initialize it.

sys$create_galaxy_lock(lcktbl_handle, name, timeout, size, ipl, rank, handle)

parameter	size (bytes)	type	usage
lcktbl_handle	4	input by value	lock table handle
name	8	input by ref	address of 16 byte ASCIZ name of galaxy lock
timeout	4	input by value	default wait timeout (10 microsecond units)
size	4	input by value	size of lock
ipl	4	input by value	IPL of lock (kernel mode only)
rank	4	input by value	rank of lock (not implemented)
handle	8	output by ref	handle for the new lock

Return status:

• SS$_ACCVIO
• SS$_BADLCKTBL
• SS$_BADPARAM
• SS$_CREATED
• SS$_IVLOCKID
• SS$_IVLOCKTBL
• SS$_INSFMEM
• SS$_NOPRIV
• SS$_NOSHMEM
• SS$_NORMAL

This services uses SYS$RESET_GALAXY_LOCK to invalidate the galaxy lock and to delete it. The memory for the lock is not truly deleted, but is put on a free list for later use.

sys$delete_galaxy_lock(handle)

parameter	size (bytes)	type	usage
handle	8	input by value	galaxy lock handle

Return status:

• SS$_BADLCKTBL
• SS$_IVLOCKID
• SS$_IVLOCKTBL
• SS$_LOCKINUSE
• SS$_NORMAL
• SS$_NOPRIV
• SS$_NOSHMEM

This service returns all "interesting" fields from the specified lock.

sys$get_galaxy_lock_info(handle, name, timeout, size, ipl, rank, flags)

parameter	size (bytes)	type	usage
handle	8	input by value	galaxy lock handle
name	8	output by ref	address of 16 byte ASCIZ name of galaxy lock
timeout	4	output by ref	default wait timeout
size	4	output by ref	size of lock structure
ipl	4	output by ref	IPL of lock
rank	4	output by ref	rank of lock
flags	2	output by ref	flags field in galaxy lock structure

Return status:

• SS$_IVLOCKID
• SS$_NORMAL

This service returns the minimum and maximum size of a galaxy lock. If a lock is created with the maximum size, the locking services will record acquire and release information in the lock.

sys$get_galaxy_lock_size(min_size, max_size)

parameter	size (bytes)	type	usage
min_size	4	output by ref	Minimum size of galaxy lock
max_size	4	output by ref	Maximum size of galaxy lock

Return status:

• SS$_NORMAL

This service is used to acquire ownership of a 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 SYS$CREATE_GALAXY_LOCK or SYS$INIT_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 a galaxy instance shutting down, a lock may become owned by a non-existent entity. If this occurs, the default behavior of SYS$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, SYS$ACQUIRE_GALAXY_LOCK will not break the lock ownership and returns SS$_NOBREAK.

sys$acquire_galaxy_lock(handle, timeout, flags)

parameter	size (bytes)	type	usage
handle	8	input by value	galaxy lock handle
timeout	4	input by value	wait timeout (overrides default)
flags	4	input by value	GLOCK$C_NOWAIT GLOCK$C_NOSPIN GLOCK$C_NOBREAK

Return status:

• SS$_BADPARAM
• SS$_BROKEN
• SS$_IVLOCKID
• SS$_IVLOCKOP
• SS$_IVLOCKTBL
• SS$_LOCK_TIMEOUT
• SS$_NOBREAK
• SS$_NOWAIT
• SS$_NORMAL

This service releases ownership of a galaxy lock. Because a galaxy lock can be acquired multiple times by the same owner (nested ownership), the lock is not released until the ownership count goes to zero. If the lock ownership is completely released and there are other threads waiting for the lock, they are released from their wait states.

sys$release_galaxy_lock(handle)

parameter	size (bytes)	type	usage
handle	8	input by value	galaxy lock handle

Return status:

• SS$_IVLOCKID
• SS$_IVLOCKOP
• SS$_IVLOCKTBL
• SS$_NORMAL

IVLOCKOP <invalid lock operation> An attempt was made to release a lock that is not owned. Check that all calls to acquire a lock are matched by calls to release it. IVLOCKTBL <invalid lock table> The lock table handle passed to the locking service does not represent a valid lock table. Verify that the lock table handle being used is the same as that returned by SYS$CREATE_GALAXY_LOCK_TABLE or SYS$INIT_GALAXY_LOCK_TABLE. LOCKINUSE <invalid operation; lock is in use> An attempt was made to delete a lock which is in use or to initialize a lock which is already initialized Verify that the lock handle being used is the same as that returned by SYS$CREATE_GALAXY_LOCK or SYS$INIT_GALAXY_LOCK. LOCK_TIMEOUT <failed to acquire lock; request has timed out> An attempt to acquire a lock did not complete during the timeout period. This problem could be caused by a timeout value that is too small. It can also be caused by a thread holding the lock for too long. BADLCKTBL <galaxy lock table is corrupt> The list of locks in the specified lock table is corrupt. Lock tables are writable from the access mode in which they are created. Verify that the application is not overwriting the lock table. NOBREAK <failed to acquire lock; lock ownership is broken> An attempt to acquire a lock failed because the lock ownership had been broken and GLOCK$C_NOBREAK was specified on the call to SYS$ACQUIRE_GALAXY_LOCK. Lock ownership being broken can be the result of a process or system failure while a lock is held. Depending on how the lock is used, this could mean that the data this lock protects is corrupt. NOWAIT <failed to acquire lock; NOWAIT was specified> An attempt to acquire a lock failed because the lock is currently owned and GLOCK$C_NOWAIT was specified on the call to SYS$ACQUIRE_GALAXY_LOCK The application must either retry the operation or wait for the lock to become available. BROKEN <lock acquired after lock ownership was broken.> An attempt to acquire a lock succeeded but the previous owner of the lock no longer existed and its ownership was broken. Lock ownership being broken can be the result of a process or system failure while a lock is held. Depending on how the lock is used, this could mean that the data this lock protects is corrupt.

Applications can register to be notified when certain system events occur; for example, when an instance joins the galaxy or if a CPU joins a configure set. If events are registered, an application can decide how to respond when the registered events occur.

15.1 SYS$SET_SYSTEM_EVENT

Set System Event

Establishes a request for notification when an OpenVMS system event occurs.

Format:

SYS$SET_SYSTEM_EVENT (event ,astadr ,astprm, acmode, flags, handle)

C Prototype:

int sys$set_system_event (unsigned int event, void (*astadr)(__unknown_params), int astprm, unsigned int acmode, unsigned int flags, struct _generic_64 * handle;

Arguments:

event

OpenVMS usage:	event_code
type:	longword (unsigned)
access:	read only
mechanism:	by value

Event code indicating the type of system event for which an AST is to be delivered. The event argument is a value indicating which type of event is of interest.

Each event type has a symbolic name. The $SYSEVTDEF macro defines the following symbolic names.

Symbolic Name	Description
SYSEVT$C_ADD_MEMBER	One or more OpenVMS instances have joined the OpenVMS Galaxy sharing community.
SYSEVT$C_DEL_MEMBER	One or more OpenVMS instances have left the OpenVMS Galaxy sharing community.
SYSEVT$C_ADD_ACTIVE_CPU	One or more processors have become active within this OpenVMS instance.
SYSEVT$C_DEL_ ACTIVE_CPU	One or more processors have become inactive within this OpenVMS instance
SYSEVT$C_ADD_CONFIG_CPU	One or more processors have become active within this OpenVMS instance.
SYSEVT$C_DEL_CONFIG_CPU	One or more processors have become inactive within this OpenVMS instance.

astadr

OpenVMS usage:	ast_procedure
type:	procedure value
access:	call without stack unwinding
mechanism:	by 32-bit or 64-bit reference

Notification AST routine to receive control after a change in OpenVMS system configuration occurs.

astprm

OpenVMS usage:	user_arg
type:	quadword
access:	read only
mechanism:	by value

The quadword AST parameter to be passed to the AST routine.

acmode

OpenVMS usage:	access_mode
type:	longword (unsigned )
access:	read only
mechanism:	by value

Access mode at which the system event AST is to execute. The acmode argument is a longword containing the access mode.

Each access mode has a symbolic name. The $PSLDEF macro defines the following symbols for the four access modes.

Symbolic Name	Description
PSL$C_KERNEL	Kernel
PSL$C_EXEC	Executive
PSL$C_SUPER	Supervisor
PSL$C_USER	User

The value of the access mode is maximized with the access mode of the caller.

flags

Defined in SYSEVTDEF.

SYSEVT$M_REPEAT_NOTIFY

When this flag is set, event notification will be repeated.

handle

OpenVMS usage:	handle
type:	quadword (unsigned)
access:	read/write
mechanism:	by reference

The virtual address of a naturally aligned quadword for the event handle.

Description

The Set System Event service establishes a request for notification when a system event occurs. It may create a new system event notification object, add an event to a (new or existing) object, and enable notification on a (new or existing) object.

If the handle specified is zero, a new system notification request object is created, and a handle for the new object is returned.

If the event specified is non-zero, that event is added to the set of events which trigger notification on the notification object.

The service will verify that the input parameters specify a valid request and enable the object for notification. Notification is accomplished by AST delivery. After the AST has been delivered, notification must again be enable on the object before another notification (AST delivery) can occur if flag is not set.

Errors will be returned in the following cases:

• If quotas are exceeded, an error will be returned. It is important to note that this routine will return an error and will not retry an attempt to get quota if quota is exhausted on the first attempt.
• See the Condition Values Returned section for types of errors that can be returned.
• If the astadr argument is omitted, and a new notification object is being created, SS$_BADPARAM will be returned.
• If the event argument is incorrectly specified, SS$_BADPARAM will be returned.
• If the access mode parameter is more privileged than the mode of the caller, the mode of the caller will be used.
• If specified, the handle argument must be writeable from the mode of the caller. SS$_ACCVIO is returned if this is not the case.

Required Privileges

None.

Required Quota

ASTLM.

Related Services

$CLEAR_SYSTEM_EVENT

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The service cannot access the locations specified by one or more arguments.
SS$_BADPARAM	One of more arguments has an invalid value.
SS$_EXASTLM	The process exceeded its quota for outstanding ASTs.
SS$_INSFMEM	The system dynamic memory is insufficient to complete the service.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

6512PRO_008.HTML