_spin_trylock(SYNCH)

_spin_trylock -- conditionally lock a spin lock

Synopsis

   cc [options] -Kthread file
   
   #include <synch.h>
   

   int _spin_trylock(spin_t *lock);

Description

_spin_trylock attempts once to lock the spin lock pointed to by lock.

If lock is available, _spin_trylock will return successfully with lock locked. If lock is already locked, _spin_trylock immediately returns EBUSY to the caller without acquiring lock or spinning.

lock must previously have been initialized (see _spin_init).

Parameters

lock: pointer to spin lock to be locked

Usage

Because spin locks waste system resources, most applications should use mutexes instead of spin locks for mutual exclusion. In general, _spin_trylock, like _spin_lock(SYNCH) is used when the resources are held exclusively for such short durations that the expected spin is less costly than blocking and resuming the thread.

Spin locks should only be used when there is a guarantee that the thread will not be preempted or blocked while holding a spin lock.

The locks acquired with _spin_trylock should be released with _spin_unlock(SYNCH).

Return values

_spin_trylock returns zero for success and an error number for failure.

Errors

If the following condition occurs, _spin_trylock returns the corresponding value:

EBUSY: lock is already locked

Warnings

Spin locks must not be used on a single processor system. In the best case, a spin lock on a single processor system will waste resources, slowing down the owner of the lock; in the worst case, it will deadlock the processor.

References

Intro(SYNCH), _spin(SYNCH), _spin_destroy(SYNCH), _spin_init(SYNCH), _spin_lock(SYNCH), _spin_unlock(SYNCH)