ss_m::lock(SSM)

Shore Programmer's Manual - 2 August 96

NAME

SYNOPSIS

#include <sm_vas.h>  // which includes sm.h

static rc_t                 lock(
    const lvid_t&               lvid,
    lock_mode_t                 mode,
    lock_duration_t             duration = t_long,
    long                        timeout = WAIT_SPECIFIED_BY_XCT,
    bool			optimistic = FALSE);

static rc_t                 lock(
    const lvid_t&               lvid,
    const serial_t&             serial,
    lock_mode_t                 mode,
    lock_duration_t             duration = t_long,
    long                        timeout = WAIT_SPECIFIED_BY_XCT,
    bool			optimistic = FALSE);

static rc_t                 unlock(
    const lvid_t&               lvid,
    const serial_t&             serial);
static rc_t                 query_lock(
    const lvid_t&               lvid,
    const serial_t&             serial,
    lock_mode_t&                mode,
    bool			implicit = FALSE);

static rc_t                 set_lock_cache_enable(bool enable);
static rc_t                 lock_cache_enabled(bool& enabled);

DESCRIPTION

Locks are acquired implicitly by many ss_m methods. For those situations where more precise control of locking is desired, the following methods allow explicit locking and unlocking.

lock(lvid, mode, duration, timeout, optimistic)

lock(lvid, serial, mode, duration, timeout, optimistic)

The lock method is used to acquire a lock on volume, index, file or record. The first version of the method locks the volume specified by lvid. The second version locks the index, file or record specified by lvid,serial. The mode parameter specifies the lock mode to acquire. Valid lock_mode_t values are listed in \fC basics.h\fR. The duration parameter specifies how long the lock will be held. Valid values (among those listed in \fCbasics.h\fR) are: t_instant, t_short and t_long. The timeout parameter specifies how long to wait for a lock. The optimistic parameter should be set to true when (a) we don't want the lock request to block (due to lock conflicts) and (b) we want to get the lock "fast". If optimistic is true, then the lock mgr will first check whether any remote servers need to get involved. Since going over the network does not satisfy (b), lock() will, in this case, return with an eMAYBLOCK error code, without acquiring any lock. If no remote servers need to be contacted, then lock will try to get the local lock with a 0 timeout. If a conflict is detected, lock will again return the eMAYBLOCK error code, without acquiring any lock. Note: if optimistic is true, then timeout is irrelevant.

unlock(lvid, serial)

The unlock method releases the most recently acquired lock on the file, index, or record identified by lvid,serial. Note, that only locks with duration t_short can be released before end-of-transaction.

query_lock(lvid, serial, mode, implicit)

The query_lock method the mode of the lock held on lvid,serial by the current transaction. The lock mode is returned in mode and will be NL (no lock) if not locked. If implicit is false then only explicit locks on lvid,serial will be considered. For example, if file F is SH locked and a query is made about a record in F, the mode returned will be NL.However, if implicit is true, then SH would be returned for this example.

Lock Cache Control

Each transaction has a cache of recently acquired locks The following methods control the use of the cache. These are not supported methods and may be removed in later versions of the software. Note: that the methods only affect the transaction associated with the current thread.

set_lock_cache_enable(enable)

The set_lock_cache_enable method turns on the cache if enable is true and turns it off otherwise.

lock_cache_enabled(enabled)

The lock_cache_enabled method sets enabled to true if the lock cache is on.

ERRORS

EXAMPLES

VERSION

SPONSORSHIP

COPYRIGHT

SEE ALSO