osfmk/man/lock_handoff.html

   1 <h2>lock_handoff</h2>
   2 <hr>
   3 <p>
   4 <strong>Function</strong> - Hand-off ownership of a lock.
   5 <h3>SYNOPSIS</h3>
   6 <pre>
   7 <strong>kern_return_t   lock_handoff</strong>
   8                 <strong>(lock_set_t</strong>                            <var>lock_set</var>,
   9                  <strong>int</strong>                                    <var>lock_id</var><strong>);</strong>
  10 </pre>
  11 <h3>PARAMETERS</h3>
  12 <dl>
  13 <p>
  14 <dt> <var>lock_set</var>
  15 <dd>
  16 [in send right] The port naming the lock set which represents the
  17 lock.
  18 <p>
  19 <dt> <var>lock_id</var>
  20 <dd>
  21 [in scalar] The lock, represented by the lock set, to be handed off.
  22 </dl>
  23 <h3>DESCRIPTION</h3>
  24 <p>
  25 The <strong>lock_handoff</strong> function passes lock ownership from the calling
  26 thread to an anonymous accepting thread. The lock must be owned by the
  27 calling thread. If the accepting thread is not waiting to receive the
  28 lock, the calling thread will block until the hand-off is accepted.
  29 <h3>RETURN VALUES</h3>
  30 <dl>
  31 <p>
  32 <dt> <strong>KERN_INVALID_ARGUMENT</strong>
  33 <dd>
  34 The specified lock_set is invalid, or the lock_id is out of range.
  35 <p>
  36 <dt> <strong>KERN_INVALID_RIGHT</strong>
  37 <dd>
  38 The calling thread does not own the lock being handed off.
  39 <p>
  40 <dt> <strong>KERN_SUCCESS</strong>
  41 <dd>
  42 The lock hand-off was successful.
  43 <p>
  44 <dt> <strong>KERN_LOCK_SET_DESTROYED</strong>
  45 <dd>
  46 The specified lock has been destroyed.
  47 <p>
  48 <dt> <strong>KERN_ABORTED</strong>
  49 <dd>
  50 While blocked to wait for the accepting thread to assume the lock's ownership,
  51      the calling thread was awoken by an unrelated event;
  52      the lock's handoff state is cleared.
  53 </dl>
  54 <h3>RELATED INFORMATION</h3>
  55 <p>
  56 Functions:
  57 <a href="lock_acquire.html"><strong>lock_acquire</strong></a>,
  58 <a href="lock_release.html"><strong>lock_release</strong></a>,
  59 <a href="lock_try.html"><strong>lock_try</strong></a>,
  60 <a href="lock_handoff_accept.html"><strong>lock_handoff_accept</strong></a>,
  61 <a href="lock_make_stable.html"><strong>lock_make_stable</strong></a>,
  62 <a href="lock_set_create.html"><strong>lock_set_create</strong></a>,
  63 <a href="lock_set_destroy.html"><strong>lock_set_destroy</strong></a>.