*I*Berkeley DB: DbLockTab::vec[P

DbLockTab::vec





#include <db_cxx.h>

int1DbLockTab::vec(u_int32_t locker, u_int32_t flags,7 DB_LOCKREQ list[], int nlist, DB_LOCKREQ **elistp);





Description



KThe DbLockTab::vec method atomically obtains and releases one or more locksFfrom the lock table. The DbLockTab::vec method is intended to supportHacquisition or trading of multiple locks under one lock table semaphore,Fas is needed for lock coupling or in multigranularity locking for lock escalation.

EThe locker argument specified to DbLockTab::vec is an unsignedJ32-bit integer quantity. It represents the entity requesting or releasing the lock.

?The flags value must be set to 0 or the following value:

a

DB_LOCK_NOWAIT
If a lock cannot be granted because the requested lock conflicts with anDexisting lock, return immediately instead of waiting for the lock tobecome available.


@The list array provided to DbLockTab::vec is typedef'd asFDB_LOCKREQ. A DB_LOCKREQ structure has at least the following fields,8which must be initialized before calling DbLockTab::vec:

U

lockop_t op;
The operation to be performed, which must be set to one of thefollowing values:
\

DB_LOCK_GET
Get a lock, as defined by the values of locker, obj, and mode.FUpon return from DbLockTab::vec, if the lock field is non-NULL,1a reference to the acquired lock is stored there.?(This reference is invalidated by any call to DbLockTab::vec orPDbLock::put that releases the lock.)_

DB_LOCK_PUT
The lock referenced by the contents of the lock field is released.K

DB_LOCK_PUT_ALL
All locks held by the locker are released.H(Any locks acquired as a part of the current call to DbLockTab::vec that=appear after the DB_LOCK_PUT_ALL entry are not considered forthis operation).a

DB_LOCK_PUT_OBJ
All locks held by the locker, on the object obj, with theEmode specified by lock_mode, are released. A lock_mode>of DB_LOCK_NG indicates that all locks on the object should beHreleased. Note that any locks acquired as a part of the current call to>DbLockTab::vec that occur before the DB_LOCK_PUT_OBJ will also<be released; those acquired afterwards will not be released.
c

const Dbt obj;
An untyped byte string that specifies the object to be locked or released.a

const lockmode_t mode;
The lock mode, used as an index into lt's conflict array.)

DB_LOCK lock;
A lock reference.


AThe nlist argument specifies the number of elements in thelist array.

KIf any of the requested locks cannot be acquired, or any of the locks to beLreleased cannot be released, the operations before the failing operation areGguaranteed to have completed successfully, and DbLockTab::vec returns aHnon-zero value. In addition, if elistp is not NULL, it is set toOpoint to the DB_LOCKREQ entry that was being processed when the error occurred.

GIn the case of an error, DbLockTab::vec may return one of the followingvalues:

c

DB_LOCK_DEADLOCK
The specified locker was selected as a victim in order to resolve a deadlock._

DB_LOCK_NOTHELD
The lock cannot be released, as it was not held by the locker._

DB_LOCK_NOTGRANTED
A lock was requested that could not be granted and the flag$parameter was set to DB_LOCK_NOWAIT.HIn this case, if non-NULL, elistp identifies the request that wasgranted.


Otherwise, the DbLockTab::vec>method either returns errno or throws an exception that:encapsulates an errno on failure, and 0 on success.



Errors

UIf a fatal error occurs in Berkeley DB, the DbLockTab::vec method may fail and eitherIreturn DB_RUNRECOVERY or throw an exception encapsulating DB_RUNRECOVERY,Gat which point all subsequent database calls will also fail in the sameFway. Methods marked as returning errno will, by default, throwHan exception that encapsulates the error information. The default error\behavior can be changed, see
DbException.

The DbLockTab::vec&method may fail and throw an exceptionKfor any of the errors specified for the following Berkeley DB and C library functions: abort(3), fcntl(3), fflush(3), fprintf(3), fsync(3), getpid(3), isprint(3),DDbLockTab::detect, lseek(3), memcpy(3), memset(3),mmap(3), munmap(3), printf(3),pstat_getdynamic(3), shmat(3), shmdt(3), strerror(3), sysconf(3), vfprintf(3), vsnprintf(3),and write(3).

In addition, the DbLockTab::vec&method may fail and throw an exceptionor return errnofor the following conditions:

L

EACCES
An attempt was made to release lock held by another locker.
B

EINVAL
An invalid flag value or parameter was specified.







Class

:DbLockTab



See Also

BDbLockTab::close,DDbLockTab::detect,>DbLockTab::get,<DbLockTab::id,@DbLockTab::open,?DbLockTab::statCDbLockTab::unlinkandDbLockTab::vec.
ÿÿ