 |
Index for
Section 4 |
|
 |
Alphabetical
listing for D |
|
 |
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 conversion or multiple resource deadlock.
· 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 Cluster Highly Available Applications
|
Index for
Section 4 |
|
|
Alphabetical
listing for D |
|
 |
Top of
page |
|