Index Index for
Section 4
Index Alphabetical
listing for D
Bottom of page Bottom of
page

dlm(4)

NAME

dlm.h - Contains definitions and variables used by distributed lock manager (DLM) functions

DESCRIPTION

The /usr/include/sys/dlm.h file defines the functions and callback routines provided by the DLM, establishes symbols for the DLM lock modes and other constants, and defines the lock value block and other DLM structures. Lock Modes The following list describes each of the DLM lock modes. Note that write access implies that read access is also permitted. DLM_NLMODE Null mode (NL). This mode grants no access to the resource; it serves as a placeholder and indicator of future interest in the resource. The null mode does not inhibit locking at other lock modes; further, it prevents the deletion of the resource and lock value block, which would otherwise occur if the locks held at the other lock modes were dequeued. DLM_CRMODE Concurrent Read (CR). This mode grants the caller read access to the resource and permits write access to the resource by other users. This mode is used to read data from a resource in an unprotected manner, because other users can modify that data as it is being read. This mode is typically used when additional locking is being performed at a finer granularity with sublocks. DLM_CWMODE Concurrent Write (CW). This mode grants the caller write access to the resource and permits write access to the resource by other users. This mode is used to write data to a resource in an unprotected fashion, because other users can simultaneously write data to the resource. This mode is typically used when additional locking is being performed at a finer granularity with sublocks. DLM_PRMODE Protected Read (PR). This mode grants only read access to the resource by the caller and other users. Write access is not allowed. This is the traditional share lock. DLM_PWMODE Protected Write (PW). This mode grants the caller write access to the resource and permits only read access to the resource by other users; the other users must have specified concurrent read mode access. No other writers are allowed access to the resource. This is the traditional update lock. DLM_EXMODE Exclusive (EX). The exclusive mode grants the caller write access to the resource and permits no access to the resource by other users. This is the traditional exclusive lock. Locks that can be shared with other locks are said to have compatible lock modes. Higher-level lock modes are less compatible with other lock modes than are lower-level lock modes. If the new lock mode, as specified in the rqmode parameter of the conversion request, is compatible with the currently granted locks (that is, the resource group grant mode), the conversion request is granted immediately. If the new lock mode is incompatible with the resource group grant mode, the request is placed on the conversion queue (unless the DLM_NOQUEUE flag is specified in the request). The lock retains its granted lock mode and does not receive its new lock mode until the request is granted. The following table shows the compatibility of the lock modes. A "Yes" in a column indicates that the mode of the requested lock is compatible with the resource group grant mode; a "No" indicates that the mode of the requested lock is incompatible with the resource group grant mode. ___________________________________________________ Mode of Requested Lock Resource Group Grant Mode ___________________________________________________ -- NL CR CW PR PW EX Yes Yes Yes Yes Yes Yes Null (NL) Yes Yes Yes Yes Yes No Concurrent Read (CR) Yes Yes Yes No No No Concurrent Write (CW) Yes Yes No Yes No No Protected Read (PR) Yes Yes No No No No Protected Write (PW) Yes No No No No No Exclusive (EX) ___________________________________________________ Lock Value Blocks When a process acquires a lock on a resource, the DLM provides it with a process-private copy of the lock value block associated with the resource, provided that the process's lock request (dlm_cvt(), dlm_lock(), dlm_locktp(), dlm_quecvt(), dlm_quelock(), dlm_quelocktp(), or dlm_unlock()) specified the DLM_VALB flag and a valid address in the valb_p. This copy reflects the contents of the resource's lock value block at the time the lock request is granted. The DLM updates the resource's lock value block it maintains in the lock database as follows: · Whenever a process dequeues a lock at PW or EX mode, provided the caller specifies the DLM_VALB flag and a valid address in the valb_p parameter. · Whenever a process converts a lock at PW or EX mode to a lower lock mode, the DLM stores the caller's lock value block in the resource's lock value block, provided the caller specifies the DLM_VALB flag and a valid address in the valb_p parameter. The DLM provides an application with a copy of the resource's lock value block as follows: · When the DLM grants a new lock and the caller of the dlm_lock(), dlm_locktp(), dlm_quelock(), or dlm_quelocktp() function specifies the DLM_VALB flag, and a valid address in the valb_p parameter · When the DLM grants a request to convert a granted lock to a lock mode that is the same as or higher than its currently granted mode, provided the caller of the dlm_cvt() or dlm_quecvt() function specifies the DLM_VALB flag and a valid address in the valb_p parameter The following table shows the effect of lock conversion on the resource lock value block. A "Read" in a column indicates that the contents of the resource's lock value block are copied to the process's lock value block specified by the valb_p parameter. A "Write" indicates that the contents of the process's lock value block are written to the resource's lock value block. A triple-dash (---) indicates that no operations are performed on the lock value block. _______________________________________________________________ Mode at Which Lock Is Held Mode to Which Lock Is Converted _______________________________________________________________ -- NL CR CW PR PW EX Read Read Read Read Read Read Null (NL) --- Read Read Read Read Read Concurrent Read (CR) --- --- Read Read Read Read Concurrent Write (CW) --- --- --- Read Read Read Protected Read (PR) Write Write Write Write Write Read Protected Write (PW) Write Write Write Write Write Write Exclusive (EX) _______________________________________________________________ The DLM will mark a resource's lock value block as invalid if: · A process holding a PW or EX mode lock on the resource calls the dlm_unlock() function to dequeue this lock, and specifies the flag DLM_INVVALBLK in the flags parameter. · Any process holding a PW or EX mode lock on a resource terminates abnormally. · A node joins or leaves the cluster and the resource has only NL or CR mode locks. The reason is because a process might have been holding a PW or EX mode lock on the resource when the cluster membership changed. A process holding an NL or CR mode lock on a resource must be able to handle arbitrary invalidates of the lock value block. If the caller has requested a lock value block and the lock value block that is read is marked as valid, the DLM returns either DLM_SUCCESS or DLM_SYNC completion status (as long as the operation itself is successful). If the lock value block that is read is marked as invalid, the DLM returns a completion status of DLM_SUCCVALNOTVALID or DLM_SYNCVALNOTVALID. The DLM_SUCCVALNOTVALID and DLM_SYNCVALNOTVALID condition values are warning messages, not error messages. The request has completed successfully; the function grants the requested lock and returns this warning on all subsequent calls to dlm_lock(), dlm_locktp(), dlm_quelock(), dlm_quelocktp(), dlm_cvt(), and dlm_quecvt() until either a new lock value block is written to the lock database (causing the lock value block to be marked as valid) or the resource is deleted. Resource deletion occurs when the last lock on the resource is deleted with a dlm_unlock() function call. The DLM returns the current copy of the resource's lock value block. The DLM_SUCCVALNOTVALID and DLM_SYNCVALNOTVALID condition values indicate that this may not be the most recent value that has existed. The initial value of a lock value block prior to its first update is always zero (0). Blocking Notification Routines A process requesting a lock or a lock conversion can receive notification from the DLM that its lock is blocking a lock request from another process. At least two lock requests are involved, known as the blocking lock and the blocked lock. To enable blocking notifications, call dlm_set_signal(), specifying the signal to be used by the DLM for locking notification. Then, use the blkrtn parameter of the blocking lock request (dlm_lock(), dlm_locktp(), dlm_quelock(), dlm_quelocktp(), dlm_cvt(), or dlm_quecvt()) to specify the address of a blocking notification routine. When the DLM determines that a process holds a granted lock that is incompatible with converting or waiting locks, it calls the blocking notification routine associated with that granted lock as follows: typedef void (*blk_callback_t) ( callback_arg_t notprm, callback_arg_t blocked_hint, dlm_lkid_t *lkid, dlm_lkmode_t blocked_mode ); The DLM provides the blocking notification routine with the following parameters: notprm Context parameter of the blocking lock. This parameter was supplied by the caller of dlm_lock(), dlm_locktp(), dlm_quelock(), dlm_quelocktp(), dlm_cvt(), or dlm_quecvt() in the lock request for the blocking lock. blocked_hint hint parameter from the first blocked lock. This parameter was supplied by the caller of dlm_lock(), dlm_locktp(), dlm_quelock(), dlm_quelocktp(), dlm_cvt(), or dlm_quecvt() in the lock request for the first blocked lock. lkid Address the lock ID of the blocking lock. blocked_mode Requested mode of the first blocked lock. By the time the notification is delivered the following conditions could exist: · The lock could still be blocked. · The blocked lock could have been released by the application and, now, no locks are actually blocked. · The blocked lock could have been selected as a deadlock victim and the request failed to break a deadlock cycle. · The blocked lock could have been released by the application and another lock was queued. It is now this lock that is actually blocked. · Other locks are backed up behind the original blocked lock or subsequently queued blocked lock. All of these conditions, except for deadlock victim selection, can be controlled by an application. Completion Routines The DLM delivers a completion notification, if requested in a call to the dlm_quecvt(), dlm_quelock(), or dlm_quelocktp() function by the specification of the cplrtn parameter, when a lock request is granted, unlocked, canceled, or selected to break a deadlock. The completion routine uses the final status passed to it by the DLM to distinguish these cases. The lock reverts to its previous granted mode if it was canceled or selected to break a deadlock. The DLM calls the completion routine as follows: typedef void (*cpl_callback_t) ( callback_arg_t notprm, dlm_lkid_t *lkid, dlm_status_t completion_status ); The DLM provides the completion routine with the following parameters: notprm Parameter supplied to the original call to the dlm_lock(), dlm_locktp(), dlm_quelock(), dlm_quelocktp(), dlm_cvt(), or dlm_quecvt() function. lkid Address of the lock ID of the completing lock. This parameter is valid only if the lock is granted. completion_status Final status of the lock request. The completion routine checks the final status that is supplied to determine if the request was granted.

RELATED INFORMATION

Functions: dlm_cancel(3), dlm_cvt(3), dlm_detach(3), dlm_get_lkinfo(3), dlm_get_rsbinfo(3), dlm_glc_attach(3), dlm_glc_create(3), dlm_glc_detach(3), dlm_glc_destroy(3), dlm_lock(3), dlm_notify(3), dlm_nsjoin(3), dlm_nsleave(3), dlm_perrno(3), dlm_quecvt(3), dlm_quelock(3), dlm_rd_attach(3), dlm_rd_collect(3), dlm_rd_detach(3), dlm_rd_validate(3), dlm_set_signal(3), dlm_unlock(3) TruCluster Server Highly Available Applications

Index Index for
Section 4
Index Alphabetical
listing for D
Top of page Top of
page