 |
Index for
Section 3 |
|
 |
Alphabetical
listing for D |
|
 |
Bottom of
page |
|
dlm_quecvt(3)
NAME
dlm_quecvt - Asynchronously converts an existing lock to a new mode
LIBRARY
Distributed Lock Manager Library (libdlm.a)
SYNOPSIS
#include <sys/dlm.h>
dlm_status_t dlm_quecvt (
dlm_lkid_t *lkid_p,
dlm_lkmode_t rqmode,
dlm_valb_t *valb_p,
dlm_flags_t flags,
callback_arg_t notprm,
callback_arg_t hint,
blk_callback_t blkrtn,
uint_t timeout
cpl_callback_t cplrtn );
PARAMETERS
lkid_p Specifies the address of the lock ID of the lock to be converted.
rqmode Specifies the requested mode of the conversion:
DLM_NLMODE
Null mode (NL)
DLM_CRMODE
Concurrent Read (CR)
DLM_CWMODE
Concurrent Write (CW)
DLM_PRMODE
Protected Read (PR)
DLM_PWMODE
Protected Write (PW)
DLM_EXMODE
Exclusive (EX)
See dlm(4) for a description of lock modes and a discussion of legal lock
conversions.
valb_p When provided, specifies the address of a lock value block that
contains the number of longwords defined by the DLM_VALBLKSIZE
symbol in the dlm.h file. The lock value block contains
information about the resource that is interpreted only by the
user program. If you specify the DLM_VALB flag, you must specify
the valb_p parameter. See dlm(4) for a discussion of lock value
blocks.
flags When provided, specifies flags that modify the operation. The
flags parameter is a bit mask that is the logical OR of each bit
set, where each bit corresponds to an option. See the Flags
topic of the DESCRIPTION section of this reference page for a
description of those flags that can be specified in this
parameter.
notprm When specified, supplies a parameter to be passed to the blocking
notification routine identified by the blkrtn parameter, and the
completion routine specified by the cplrtn parameter. This
parameter replaces any notprm parameter that may have been
supplied on a prior request on this lock. See dlm(4) for a
discussion of blocking notification routines.
hint When provided, specifies a parameter to be passed to the blocking
notification routine of another lock that blocks this lock. See
dlm(4) for a discussion of blocking notification routines.
blkrtn When provided, specifies the address of a blocking notification
routine that is called whenever this lock is granted and is
blocking another lock request. You can specify a parameter to be
passed to this routine by using the notprm parameter. Specifying
NULL for blkrtn indicates that no blocking notification is
requested. This parameter replaces any blkrtn parameter that may
have been supplied on a prior request on this lock. See dlm(4)
for a discussion of blocking notification routines.
timeout When supplied, specifies, in multiples of 10 milliseconds, a
timeout value for the request. (The timeout granularity is one
second.) If the request is not completed within this interval,
the request is canceled with a DLM_TIMEOUT status. A timeout
value of zero (0) causes the lock request to never time out.
cplrtn Provides the address of a routine to be invoked when the lock
conversion request is completed. This parameter is required in
each dlm_quecvt() call. Its value replaces that of any cplrtn
parameter supplied on a prior request on this lock. You can
specify a parameter to be passed to this routine by using the
notprm parameter. See dlm(4) for a discussion of completion
routines.
DESCRIPTION
The dlm_quecvt() function requests a new mode for an existing lock, as
identified by the lkid_p parameter.
This function completes asynchronously with regard to the actual completion
or failure of the lock conversion request. It returns to the caller when
the lock manager has accepted or rejected the request. Return does not
indicate that the lock conversion request has completed. The caller must
wait for the completion routine (specified in the cplrtn parameter) to run,
either by signal delivery (see dlm_set_signal(3)) or by polling (see
dlm_notify(3)).
Flags
The dlm_flags_t structure defines a symbolic name for each flag bit. The
following list describes each flag:
DLM_NODLCKBLK
Indicates to the distributed lock manager (DLM) that the process
will give up this lock on demand, if it is blocking another lock
request. As a result, the DLM will not consider this lock
request when trying to detect either conversion or multiple
resource deadlock conditions.
A process typically specifies the DLM_NODLCKBLK flag only when it
also specifies a blocking notification routine in the blkrtn
parameter. The DLM calls a process's blocking notification
routine when the process holds a granted lock that is
incompatible with another lock on the conversion or waiting
queue.
Specifying the DLM_NODLCKBLK flag can help prevent certain false
deadlocks that can occur when blocking notifications are used.
In these deadlocks, the DLM will detect a blocking condition, but
the blocking condition will disappear as soon as the process
holding the lock executes, receives the blocking notification,
and dequeues the lock.
If the process specifies the DLM_NODLCKBLK flag, the blocking
notification routine should either dequeue the lock or convert it
to a lower lock mode without issuing any new lock requests. If
the blocking notification routine does otherwise, a genuine
deadlock could be ignored.
DLM_NODLCKWT
Indicates to the DLM that the caller is not blocked from
execution while waiting for the lock request to complete. As a
result, the DLM does not consider this lock request when trying
to detect either conversion or multiple resource deadlock
conditions.
For example, an application might specify this flag when it
intends to leave a lock request outstanding on the waiting queue
as a signaling device between processes. Be careful when you
specify this flag; improper use of the DLM_NODLCKWT flag can
cause the DLM to ignore genuine deadlocks.
DLM_NOQUEUE
Indicates that the caller does not desire to wait for the request
to be granted. When this flag is specified, the lock remains in
the original lock mode if it cannot be converted immediately.
Note that the DLM_NOQUEUE and DLM_QUECVT flags are mutually
exclusive.
DLM_SYNCSTS
Indicates that the DLM should return the successful condition
value DLM_SYNCH, if the lock request is granted immediately. In
this case, no completion notification is delivered. If the lock
request is queued successfully, but cannot be granted
immediately, the DLM returns the condition value DLM_SUCCESS to
the completion routine when the request is granted.
DLM_VALB Informs the DLM that the caller is interested in the resource's
lock value block. You must specify this flag to read or write
the resource's lock value block. When you specify the DLM_VALB
flag, you must specify the valb_p parameter. See dlm(4) for a
discussion of lock value blocks.
DLM_QUECVT
Forces the conversion request to wait behind any already queued
conversions. The conversion request is granted immediately if
there are no conversions currently queued. The DLM_NOQUEUE and
DLM_QUECVT flags are mutually exclusive.
An application uses the DLM_QUECVT flag to more equally provide
access to a resource. However, you can use the DLM_QUECVT flag
for only a subset of all possible conversions. The following
table defines the legal set of conversion requests for
DLM_QUECVT. Illegal conversion requests fail, and the
DLM_BADPARAM message is returned.
___________________________________________________________________________
Mode at Which
Lock is Held
Mode to Which Lock is Converted
___________________________________________________________________________
-- NL CR CW PR PW EX
Illegal Legal Legal Legal Legal Legal
Null (NL)
Illegal Illegal Legal Legal Legal Legal
Concurrent Read
(CR)
Illegal Illegal Illegal Illegal Legal Legal
Concurrent
Write (CW)
Illegal Illegal Illegal Illegal Legal Legal
Protected Read
(PR)
Illegal Illegal Illegal Illegal Illegal Illegal
Protected Write
(PW)
Illegal Illegal Illegal Illegal Illegal Illegal
Exclusive (EX)
___________________________________________________________________________
RETURN VALUES
Upon returning to its caller, the dlm_quecvt() function returns one of the
following values:
DLM_SUCCESS
The lock request was successfully queued.
DLM_SYNCH The lock request completed successfully; the DLM_SYNCSTS flag in
the flags parameter was specified, and the DLM was able to grant
the lock request immediately.
DLM_SYNCVALNOTVALID
The lock conversion request completed successfully; the
DLM_SYNCSTS flag in the flags parameter was specified, but the
lock value block was marked invalid. See dlm(4) for a discussion
of lock value blocks.
DLM_BADPARAM
You specified an invalid lock mode in the rqmode parameter, the
combination of granted mode and requested mode was not allowed
with the DLM_QUECVT flag, or you did not specify the address of a
completion routine in the cplrtn parameter.
DLM_CVTUNGRANT
You attempted a lock conversion on a lock that is not currently
granted.
DLM_EFAULT
An error occurred in the copy operation to or from the DLM
database.
DLM_ENOSYS
The DLM is not enabled.
DLM_INSFMEM
There is insufficient kernel memory to create the data structures
or messages needed by the DLM.
DLM_IVLOCKID
You specified an invalid or nonexistent lock identification.
DLM_LKBUSY
The lock could not be converted at this time because another
thread of the same process was manipulating the lock.
DLM_NOTQUEUED
The lock request was not queued; the DLM_NOQUEUE flag in the
flags parameter was specified, and the DLM was not able to grant
the lock request immediately.
When the lock conversion request is granted, the DLM returns one of the
following completion status values to the completion routine in the
completion_status parameter:
DLM_SUCCESS
The service completed successfully; the lock was successfully
converted.
DLM_ABORT The lock was dequeued by the dlm_unlock service before the
request was granted. In this case, the lock no longer exists.
DLM_CANCEL
The lock conversion request has been canceled and the lock has
been regranted at its previous lock mode. This condition value is
returned when the dlm_cancel function is called to cancel this
lock conversion request. If the lock is granted before dlm_cancel
can cancel the conversion request, the call to dlm_cancel returns
the condition value DLM_CANCELGRANT, and the DLM returns to the
completion routine DLM_SUCCESS status.
DLM_DEADLOCK
A deadlock was detected. The lock conversion request has been
canceled and the lock has been regranted at its previous lock
mode.
DLM_NOACCESS
The process is trying to manipulate a group lock and it is not
attached to the group lock container that holds the lock.
DLM_TIMEOUT
The lock request timed out before being granted.
FILES
/usr/include/sys/dlm.h
DLM library header file.
/usr/examples/cluster/api_ex_master.c|api_ex_client.c
Source files for an example showing lock conversion and value
block usage.
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_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)
File: dlm(4)
TruCluster Server Cluster Highly Available Applications
|
Index for
Section 3 |
|
|
Alphabetical
listing for D |
|
 |
Top of
page |
|