The shmem_lock callable service provides a general-purpose interface for managing and operating locks in shared memory. It allows an application to serialize resources that must be shared across multiple address spaces.
| Operation | Environment |
|---|---|
| Authorization: | Supervisor state or problem state, any PSW key |
| Dispatchable unit mode: | Task |
| Cross memory mode: | PASN = HASN |
| AMODE (BPX1SLK): | 31-bit |
| AMODE (BPX4SLK): | 64-bit |
| ASC mode: | Primary mode |
| Interrupt status: | Enabled for interrupts |
| Locks: | Unlocked |
| Control parameters: | All parameters must be addressable by the caller and in the primary address space. |
|
AMODE 64 callers use BPX4SLK with the same parameters. All parameter addresses and addresses in parameter structures are doublewords.
These constants are defined in the BPXYCONS macro (BPXYCONS — Constants used by services).
These constants are defined in the BPXYCONS macro (BPXYCONS — Constants used by services).
These constants are defined in the BPXYCONS macro; seeBPXYCONS — Constants used by services.
The name of a fullword (doubleword) that contains the address of the user lockword in shared memory.
The name of a fullword (doubleword) that contains the address of the lock attribute area. The LockAttrAddr parameter is for use with the SLK_INIT function only. It is intended to allow for potential extensions to the shared memory locks. Because these extensions are not currently supported, the caller of the shmem_lock service should specify a null pointer for the lock attribute area address.
The name of a fullword (doubleword) that contains the address of a fullword that the service uses either to return a lock token, or as the input lock token. When it is specified with the SLK_INIT function, the LockTokenAddr parameter is used as the address of an output area in which to return the lock token of the newly created lock. For all other functions, this parameter contains the address of the lock token that represents the lock to be operated upon.
The name of a fullword in which the shmem_lock service returns 0, if the request is successful; or -1, if it is not successful. For all successful SLK_INIT and SLK_DESTROY function requests, the shmem_lock service returns 0. For successful SLK_OBTAIN, SLK_OBTAIN_COND, and SLK_RELEASE function requests, the shmem_lock service returns a count of the number of times the calling thread has had the requested lock held.
The name of a fullword in which the shmem_lock service stores the return code. The shmem_lock service returns Return_code only if Return_value is -1. For a complete list of possible return code values, see z/OS UNIX System Services Messages and Codes. The shmem_lock service can return one of the following values in the Return_code parameter:
| Return_code | Explanation |
|---|---|
| EAGAIN | The requested service could not be performed at the current time because of a lack of available system resources. The following reason codes can accompany this return code: JRTLOCKMAXCNTTHD, JRLOCKMAXCNTSYS, JRLOCKMAXCNTRECURSE. |
| ENOMEN | The requested service could not be performed at the current time because of a lack of available system storage. |
| EINTR | A signal interrupted the callable service. |
| EINVAL | One of the parameters contains a value that is not correct. The following reason codes can accompany this return code: JRLOCKFCNCODE, JRLOCKREQTYPE, JRLOCKTYPE, JRLOCKADDR, JRLOCKTOKEN. |
| EFAULT | One of the parameters contains an address that is not accessible by the caller. The following reason code can accompany the return code: JRLOCKTOKENADDR. |
| EBUSY | The specified function cannot be performed because a required resource is already in use. The following reason codes can accompany the return code: JRLOCKINUSE, JRLOCKEDALREADY. |
| EPERM | The caller is not permitted to perform the specified operation. The following reason codes can accompany the return code: JRLOCKNOTOWNER, JRLOCKSHMACC. |
| EDEADLK | The caller already owns the lock that is requested. |
The name of a fullword in which the shmem_lock service stores the reason code. The shmem_lock service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. See z/OS UNIX System Services Messages and Codes for the reason codes.
In order for a lock initialization call to complete successfully, the specified lock address must be in a memory-mapped area or shared storage segment that is read-write accessible by the calling process. To most efficiently manipulate locks in shared storage, it is recommended that the lock be in a shared memory segment. The shmem_lock service is optimized to handle locks that reside in a shared memory segment, rather than a memory-mapped area.
A successful lock initialization call causes a lock token representing the newly created lock to be returned in the lock token output area that is supplied via the LockTokenAddr parameter. Subsequent calls to the shmem_lock service to manipulate the newly created lock must specify the returned lock token in order to identify the lock that is to be manipulated. A lock initialization call can fail if system resources other than storage are not available to initialize the lock (EAGAIN), or if not enough system storage is available (ENOMEM).
A destroy of a lock causes the system resources for that lock to be cleaned up, if the lock is not in use. If the lock is in use, the destroy request fails (EBUSY). A lock could be in use if a thread has it in a locked state, or if it is being referenced by another thread on a pthread_cond_timedwait or pthread_cond_wait. Once a lock is destroyed, any further operations against that lock fail (EINVAL).
A successful call to the shmem_lock service to obtain a shared memory lock results in a GRS latch obtain against a latch in the 'SYS.BPX.AP00.GXSLT.SHMLOCKS.LSN' latch set. If an application is experiencing serialization problems with a shared memory lock, GRS contention analysis tools such as D GRS,C and IPCS ANALYZE can be used to determine the cause of the problem. The lower halfword of the lock token that is returned by the shmem_lock service indicates the latch number of the corresponding latch within the 'SYS.BPX.AP00.GXSLT.SHMLOCKS.LSN' LATCH set.
If an exclusive obtain of a lock that is defined as both exclusive and shared is attempted by a thread that already has that lock obtained exclusively, deadlock results. Additionally, if an exclusive or shared obtain of a shared and exclusive lock is attempted by a thread that already has that lock obtained exclusively, deadlock results. To prevent exclusive obtain starvation for a lock that is defined as shared and exclusive, a new shared lock obtain blocks if there are any exclusive obtain callers waiting. A lock that is initialized with the recursive attribute can be obtained multiple times by the same thread, up to a limit of 32 768 iterations. A single thread can hold up to a limit of 128 different shared memory locks concurrently.
A lock release call against a lock that is not in a locked state or that is not owned by the calling thread results in an error (EPERM). A lock with the recursive attribute that has been obtained n times by a given thread must be released n times by that same thread in order for the lock to be completely released.
During task termination processing of a thread that ends while it is holding a shared memory lock, the lock is released by the system. If a jobstep ends abnormally (for example, if it is canceled), or if an address space is terminated at end of memory, all shared memory locks that are held by that job or address space are released.
None.
None.
For an example using this callable service, see BPX1SLK (shmem_lock) example.