SLEEP_ALLOC(D3) SLEEP_ALLOC(D3)
NAME
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);
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.
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.
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
Copyright 1994 Novell, Inc. Page 1
SLEEP_ALLOC(D3) SLEEP_ALLOC(D3)
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.
Level
Base only if flag is set to KM_SLEEP.
Initialization, Base or Interrupt if flag is set to
KM_NOSLEEP.
Synchronization Constraints
May sleep if flag is set to KM_SLEEP.
Driver-defined basic locks and read/write locks may be held
across calls to this function if flag is KM_NOSLEEP but may
not be held if flag is KM_SLEEP.
Driver-defined sleep locks may be held across calls to this
function regardless of the value of flag.
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)
NOTICES
Copyright 1994 Novell, Inc. Page 2
SLEEP_ALLOC(D3) SLEEP_ALLOC(D3)
Portability
All processors
Applicability
ddi: 5, 5mp, 6, 6mp, 7, 7mp
Copyright 1994 Novell, Inc. Page 3