SVR5

RW_ALLOC(D3)

RW_ALLOC -- allocate and initialize a read/write lock

Synopsis

   #include <sys/types.h>
   #include <sys/kmem.h>
   #include <sys/ksynch.h>
   #include <sys/ddi.h>
   
   rwlock_t *RW_ALLOC(uchar_t hierarchy, pl_t min_pl, lkinfo_t *lkinfop,
   	int flag);

Description

RW_ALLOC dynamically allocates and initializes an instance of a read/write lock. The lock is initialized to the unlocked state.

If flag is set to KM_SLEEP, the caller will sleep if necessary until sufficient memory is available. If flag is set to KM_NOSLEEP, the caller will not sleep, but RW_ALLOC will return NULL if sufficient memory is not immediately available.

Arguments

hierarchy: Hierarchy value which asserts the order in which this lock will be acquired relative to other basic and read/write locks.
min_pl: Minimum priority level argument which asserts the minimum priority level that will be passed in with any attempt to acquire this lock [see RW_RDLOCK(D3) and RW_WRLOCK(D3)].
lkinfop: Pointer to a lkinfo structure.
flag: Specifies whether the caller is willing to sleep waiting for memory.

Return values

Upon successful completion, RW_ALLOC returns a pointer to the newly allocated lock. If KM_NOSLEEP is specified and sufficient memory is not immediately available, RW_ALLOC returns a NULL pointer.

Usage

hierarchy argument

See hierarchy(D5).

min_pl argument

See pl(D5).

lkinfop argument

The lk_name member of the lkinfo structure described on the LKINFO_DECL(D5) manual page points to a character string defining a name that will be associated with the lock for the purpose of statistics gathering. The name should begin with the driver prefix and should be unique to the lock or group of locks for which the driver wishes to collect a uniquely identifiable set of statistics (that is, if a given name is shared by a group of locks, the statistics of individual locks within the group will not be uniquely identifiable). There are no flags defined within the lk_flags member of the lkinfo structure for use with RW_ALLOC.

The lkinfop pointer is recorded in a statistics buffer along with the lock statistics when the driver is compiled with the DEBUG and _MPSTATS compilation options defined. A given lkinfo structure may be shared among multiple read/write locks and basic locks but a lkinfo structure may not be shared between a read/write lock and a sleep lock. The caller must ensure that the lk_flags and lk_pad members of the lkinfo structure are zeroed out before passing it to RW_ALLOC.

flag argument

Under the _MPSTATS compilation option, if KM_NOSLEEP is specified and sufficient memory can be immediately allocated for the lock itself but not for an accompanying statistics buffer, RW_ALLOC will return a pointer to the allocated lock but individual statistics will not be collected for the lock.

Context and synchronization

If flag is set to KM_NOSLEEP, non-blockable, initialization, or interrupt context.

If flag is set to KM_SLEEP, user context.

Hardware applicability

All

Version applicability

ddi: 5, 5mp, 6, 6mp, 7, 7mp, 7.1, 7.1mp, 8, 8mp

References

hierarchy(D5), LKINFO_DECL(D5), pl(D5), RW_DEALLOC(D3), RW_RDLOCK(D3), RW_TRYRDLOCK(D3), RW_TRYWRLOCK(D3), RW_UNLOCK(D3), RW_WRLOCK(D3)

``Spin locks (DDI)'' in HDK Technical Reference