 |
Index for
Section 3 |
|
 |
Alphabetical
listing for D |
|
 |
Bottom of
page |
|
dlm_cvt(3)
NAME
dlm_cvt - Synchronously converts an existing lock to a new mode
LIBRARY
Distributed Lock Manager Library (libdlm.a)
SYNOPSIS
#include <sys/dlm.h>
dlm_status_t dlm_cvt (
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 );
PARAMETERS
lkid_p Specifies the address of the lock ID of the lock to be converted.
rqmode Specifies the requested mode of the conversion, as follows:
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
containing 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 in 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. 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.
DESCRIPTION
The dlm_cvt() function requests a new mode for an existing lock, as
identified by the lkid_p parameter. This function completes synchronously
when the lock conversion request has completed or failed, as indicated by
the completion status.
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
specifying 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 conversion request is granted
immediately. If the lock conversion request cannot be granted
immediately, the DLM returns the condition value DLM_SUCCESS 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 completion, the dlm_cvt() function returns one of the following
values:
DLM_SUCCESS
The lock conversion request was successfully granted.
DLM_SUCCVALNOTVALID
The lock conversion request completed successfully, but the
resource's lock value block was marked invalid. See dlm(4) for a
discussion of lock value blocks.
DLM_SYNCH The lock conversion request completed successfully; the
DLM_SYNCSTS flag in the flags parameter was specified, and the
DLM was able to grant the request immediately.
DLM_SYNCVALNOTVALID
The lock conversion request completed successfully; the
DLM_SYNCSTS flag in the flags parameter was specified, but the
resource's 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, you specified an illegal flag in the
flags parameter, or you specified the DLM_VALB flag but did not
specify the valb_p parameter.
DLM_CVTUNGRANT
You attempted a lock conversion on a lock that is not currently
granted.
DLM_DEADLOCK
A conversion or multiple resource deadlock was detected. The lock
conversion request has been canceled and the lock has been
regranted at its previous lock mode.
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 no lock ID, or an invalid or nonexistent lock ID.
DLM_LKBUSY
The lock could not be converted at this time because another
thread of the same process was manipulating the lock.
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_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 conversion request immediately.
DLM_TIMEOUT
The lock request has 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_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)
File: dlm(4)
TruCluster Server Cluster Highly Available Applications
|
Index for
Section 3 |
|
|
Alphabetical
listing for D |
|
 |
Top of
page |
|