 |
Index for
Section 3 |
|
 |
Alphabetical
listing for D |
|
 |
Bottom of
page |
|
dlm_quelock(3)
NAME
dlm_quelock, dlm_quelocktp - Asynchronously requests a lock
LIBRARY
Distributed Lock Manager Library (libdlm.a)
SYNOPSIS
#include <sys/dlm.h>
dlm_status_t dlm_quelock (
dlm_nsp_t nsp,
uschar_t *resnam,
ushort_t resnlen,
dlm_lkid_t *parid,
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 );
dlm_status_t dlm_quelocktp (
dlm_nsp_t nsp,
uschar_t *resnam,
ushort_t resnlen,
dlm_lkid_t *parid,
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,
dlm_trans_id_t trans_id,
dlm_rd_id_t rd_id );
PARAMETERS
nsp Identifies the namespace where the root resource exists. You
obtain this value by using the dlm_nsjoin() function to connect
to the namespace. This parameter is valid only for lock requests
with a parid of zero (0); that is, it must be zero (0) for child
locks.
resnam Specifies the name of the resource to lock. The resnam parameter
is the address of a 1 to DLM_RESNAMELEN byte string.
resnlen Specifies the length of the resource name. Resource names must
be from 1 to DLM_RESNAMELEN bytes long.
parid Specifies the lock ID of the parent lock. If you specify a value
of zero (0) for this parameter, the dlm_lock() function assumes
that the lock does not have a parent lock (that is, it is a root
lock). If you specify a nonzero value, the distributed lock
manager (DLM) considers the requested lock to be a sublock of the
specified parent.
lkid_p Receives the lock ID of the requested lock.
rqmode Specifies the mode of the requested lock, 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 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_quelock() or dlm_quelocktp() 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.
trans_id When provided in a dlm_quelocktp() call, identifies a transaction
that may manipulate the lock. The transaction may or may not span
cluster members, as indicated by the DLM_TXID_LOCAL or
DLM_TXID_GLOBAL flag. The values 0 and -1 are reserved to the
DLM. This parameter is valid only when the DLM_TXID_LOCAL or
DLM_TXID_GLOBAL flag is specified.
The scope of a transaction ID is limited to a namespace. The same
value in different namespaces indicates different transactions;
the same value in a single namespace indicates the same
transaction.
The DLM uses transaction IDs to fine tune its deadlock search
mechanism when process IDs and group IDs do not clearly reflect
lock ownership. If two locks have different transaction IDs, the
DLM considers them to have different owners, even if they have
been taken by the same process or processes with the same group
ID. If two locks have the same transaction ID, the DLM considers
them to have the same owner, even if they have been taken by
processes with different process or group IDs.
rd_id Specifies the recovery domain ID returned by a previous call to
dlm_rd_attach(). Use this parameter with the DLM_PERSIST flag to
lock a persistent resource on a dlm_quelocktp() call. If the
resource does not exist, it is created as a persistent resource.
(If the DLM_PERSIST flag is not specified, the rd_id parameter is
ignored and the resource is treated as nonpersistent.)
A single recovery domain can contain multiple persistent
resources; however, a single resource cannot belong to more than
one recovery domain.
See dlm_rd_attach(3) for a discussion of persistent resources and
recovery domains.
DESCRIPTION
The dlm_quelocktp() function requests a new lock on a resource. It is
identical to the dlm_quelock() function except that it supports the use of
group locks, transaction IDs, and persistent resources.
This function completes asynchronously with regard to the actual completion
or failure of the lock request. It returns to the caller when the DLM has
accepted or rejected the request. Its return does not indicate that the
lock request is granted. The caller must wait for the completion routine
(specified in the cplrtn parameter) to run. See dlm_set_signal(3) and
dlm_notify(3) for more information.
Flags
The dlm_flags_t structure defines a symbolic name for each flag bit. The
following list describes each flag:
DLM_GROUP_LOCK
Indicates that the lock is to be a group lock held by the group
lock container to which the process is attached. It can be
manipulated by other processes that are attached to the same
group lock container. This flag is valid only in a dlm_quelocktp
function call.
DLM_NODLCKBLK
Indicates to the 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 request is
not queued if it cannot be granted immediately.
DLM_PERSIST
Locks a persistent resource belonging to the recovery domain
identified by the rd_id parameter. It is an error to lock a
persistent resource without specifying the DLM_PERSIST flag.
Likewise, it is an error to lock a nonpersistent resource by
specifying the flag. See dlm_rd_attach(3) for a discussion of
persistent resources and recovery domains.
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_TXID_GLOBAL
Indicates that the lock is to be manipulated by a transaction
that may span cluster members, and that the DLM should use the
value in the trans_id argument to detect deadlocks among locks
with the same transaction ID. This flag is valid only in a
dlm_quelocktp() function call.
DLM_TXID_LOCAL
Indicates that the lock is to be manipulated by a transaction
that will not span cluster members, and that the DLM should use
the value in the trans_id argument to detect deadlocks among
locks with the same transaction ID. This flag is valid only in a
dlm_quelocktp() function call.
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.
RETURN VALUES
Upon returning to its caller, the dlm_quelock() or dlm_quelocktp() 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 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, a
nonzero parid with the nsp parameter, a trans_id of 0 or -1, or
an rd_id parameter that was out of the range of valid resource
domain IDs. You did not specify the address of a completion
routine in the cplrtn parameter.
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 necessary data
structures.
DLM_IS_PR An attempt was made to lock a persistent resource as
nonpersistent.
DLM_IVBUFLEN
The length of the resource name was either zero (0) or greater
than DLM_RESNAMELEN characters.
DLM_IVLOCKID
You specified an invalid or nonexistent lock identification for
the parent lock.
DLM_IVRDID
No existing recovery domain corresponds to the value of the rd_id
parameter.
DLM_NO_GROUP
The DLM_GROUP_LOCK flag was specified and the process is not
attached to a group lock container.
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.
DLM_NOT_PR
An attempt was made to lock a nonpersistent resource as
persistent.
DLM_PARNOTGRANT
The parent lock specified in the parid parameter was not granted.
DLM_PR_RD_MISMATCH
An attempt was made to lock an existing persistent resource in
one recovery domain with an rd_id value that refers to another
recovery domain.
When the lock 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
granted.
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_DEADLOCK
A deadlock was detected and this request is not granted.
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_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_locktp(3),
dlm_notify(3), dlm_nsjoin(3), dlm_nsleave(3), dlm_perrno(3), dlm_quecvt(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 |
|