SVR5

SLEEP_ALLOC(D3)

SLEEP_ALLOC -- allocate and initialize a sleep lock

Synopsis

   #include <sys/types.h>
   #include <sys/kmem.h>
   #include <sys/ksynch.h>
   #include <sys/ddi.h>
   
   sleep_t *SLEEP_ALLOC(int arg, lkinfo_t *lkinfop, int flag);

Description

SLEEP_ALLOC dynamically allocates and initializes an instance of a sleep 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 SLEEP_ALLOC will return NULL if sufficient memory is not immediately available.

Arguments

arg: Reserved for future use (must be equal to zero).
lkinfop: Pointer to a lkinfo structure (see LKINFO_DECL(D5)). The lk_name member of the lkinfo structure points to a character string defining a name that will be associated with the lock for the purpose of statistics gathering.
flag: Specifies whether the caller is willing to sleep waiting for memory.

Return values

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

Usage

lkinfop argument

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). The only bit flag currently specified within the lk_flags member of the lkinfo structure is the LK_NOSTATS flag, which specifies that statistics are not to be collected for this particular lock under the _MPSTATS compilation option. If the LK_NOSTATS flag is not specified, statistics will be collected for this lock under the _MPSTATS compilation option, and the lkinfop pointer will be recorded in the statistics buffer along with the lock statistics.

A given lkinfo structure may be shared among multiple sleep locks but a lkinfo structure may not be shared between a sleep lock and a basic or read/write lock. The caller must ensure that the lk_pad member of the lkinfo structure is zeroed out before passing it to SLEEP_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, SLEEP_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

LKINFO_DECL(D5), SLEEP_DEALLOC(D3), SLEEP_LOCK(D3), SLEEP_LOCK_SIG(D3), SLEEP_LOCKAVAIL(D3), SLEEP_LOCKOWNED(D3), SLEEP_TRYLOCK(D3), SLEEP_UNLOCK(D3)

``Sleep locks'' in HDK Technical Reference