share/man/man9/serializer.9

   1 .\"
   2 .\" Copyright (c) 2007
   3 .\"     The DragonFly Project.  All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\"
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in
  13 .\"    the documentation and/or other materials provided with the
  14 .\"    distribution.
  15 .\" 3. Neither the name of The DragonFly Project nor the names of its
  16 .\"    contributors may be used to endorse or promote products derived
  17 .\"    from this software without specific, prior written permission.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  22 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
  23 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  24 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
  25 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  26 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  27 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  28 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  29 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .Dd January 17, 2014
  33 .Dt SERIALIZER 9
  34 .Os
  35 .Sh NAME
  36 .Nm lwkt_serialize_init ,
  37 .Nm lwkt_serialize_enter ,
  38 .Nm lwkt_serialize_adaptive_enter ,
  39 .Nm lwkt_serialize_try ,
  40 .Nm lwkt_serialize_exit ,
  41 .Nm lwkt_serialize_handler_enable ,
  42 .Nm lwkt_serialize_handler_disable ,
  43 .Nm lwkt_serialize_handler_call ,
  44 .Nm lwkt_serialize_handler_try ,
  45 .Nm LWKT_SERIALIZE_INITIALIZER ,
  46 .Nm ASSERT_SERIALIZED ,
  47 .Nm ASSERT_NOT_SERIALIZED
  48 .Nd generic low level serializer
  49 .Sh SYNOPSIS
  50 .In sys/serialize.h
  51 .Ft void
  52 .Fn lwkt_serialize_init "lwkt_serialize_t s"
  53 .Ft void
  54 .Fn lwkt_serialize_enter "lwkt_serialize_t s"
  55 .Ft void
  56 .Fn lwkt_serialize_adaptive_enter "lwkt_serialize_t s"
  57 .Ft int
  58 .Fn lwkt_serialize_try "lwkt_serialize_t s"
  59 .Ft void
  60 .Fn lwkt_serialize_exit "lwkt_serialize_t s"
  61 .Ft void
  62 .Fn lwkt_serialize_handler_enable "lwkt_serialize_t s"
  63 .Ft void
  64 .Fn lwkt_serialize_handler_disable "lwkt_serialize_t s"
  65 .Ft void
  66 .Fo lwkt_serialize_handler_call
  67 .Fa "lwkt_serialize_t s"
  68 .Fa "void (*func)(void *, void *)"
  69 .Fa "void *arg"
  70 .Fa "void *frame"
  71 .Fc
  72 .Ft int
  73 .Fo lwkt_serialize_handler_try
  74 .Fa "lwkt_serialize_t s"
  75 .Fa "void (*func)(void *, void *)"
  76 .Fa "void *arg"
  77 .Fa "void *frame"
  78 .Fc
  79 .Pp
  80 .Nm LWKT_SERIALIZE_INITIALIZER ;
  81 .Fn ASSERT_SERIALIZED "s"
  82 .Fn ASSERT_NOT_SERIALIZED "s"
  83 .Sh DESCRIPTION
  84 The
  85 .Nm serializer
  86 API provides a fast locked-bus-cycle-based serialization facility
  87 that will serialize across blocking conditions.
  88 It is very similar to a lock but much faster for the common case.
  89 .Pp
  90 This API was initially designed to be a replacement for SPL calls,
  91 but may be used whenever a low level exclusive lock (serialization)
  92 and/or interrupt/device interaction is required.
  93 If it is used by interrupt,
  94 callers should enter critical section to prevent the current thread
  95 holding the serializer being preempted by interrupt thread
  96 which may try to hold the same serializer.
  97 Unlike tokens this serialization is not safe from deadlocks
  98 nor is it recursive,
  99 and care must be taken when using it.
 100 Note that
 101 .Xr tsleep 9
 102 will not release a serializer that is being held.
 103 .Pp
 104 There are two primary facilities \(em the serializer facility itself and
 105 an integrated non-stackable interrupt handler disablement facility
 106 used by drivers.
 107 .Pp
 108 .Fn lwkt_serialize_init ,
 109 .Fn lwkt_serialize_enter
 110 and
 111 .Fn lwkt_serialize_exit
 112 respectively initialize, hold and release the serializer
 113 .Fa s .
 114 .Fn lwkt_serialize_try
 115 is a non-blocking version of
 116 .Fn lwkt_serialize_enter .
 117 .Pp
 118 .Fn lwkt_serialize_adaptive_enter
 119 is a special version of
 120 .Fn lwkt_serialize_enter
 121 which will try to spin a bit before the current thread is put to sleep
 122 if the serializer
 123 .Fa s
 124 is contended.
 125 By default,
 126 .Fn lwkt_serialize_adaptive_enter
 127 favors spinning over sleeping.
 128 .Pp
 129 .Fn lwkt_serialize_handler_disable ,
 130 .Fn lwkt_serialize_handler_enable
 131 and
 132 .Fn lwkt_serialize_handler_call
 133 respectively disable, enable and call an interrupt handler
 134 .Fa func
 135 for the serializer
 136 .Fa s .
 137 The arguments
 138 .Fa arg
 139 and
 140 .Fa frame
 141 will be passed to the handler.
 142 .Fn lwkt_serialize_handler_try
 143 is a non-blocking version of
 144 .Fn lwkt_serialize_handler_call .
 145 .Pp
 146 The macro
 147 .Nm LWKT_SERIALIZE_INITIALIZER
 148 evaluates to an initializer for the serializer.
 149 .Pp
 150 The
 151 .Fn ASSERT_SERIALIZED
 152 and
 153 .Fn ASSERT_NOT_SERIALIZED
 154 macros assert that the serializer
 155 .Fa s
 156 is being held/not held.
 157 .Sh RETURN VALUES
 158 The
 159 .Fn lwkt_serialize_handler_try
 160 function return 0 on success and 1 on failure.
 161 The
 162 .Fn lwkt_serialize_try
 163 function return 1 on success and 0 on failure.
 164 .Sh FILES
 165 The serializer itself is implemented in
 166 .Pa /sys/kern/lwkt_serialize.c .
 167 The header file
 168 .Pa /sys/sys/serialize.h
 169 describes the public interface and the structure of a serializer.
 170 .Sh SEE ALSO
 171 .Xr crit_enter 9 ,
 172 .Xr spinlock 9 ,
 173 .Xr zsleep 9
 174 .Sh HISTORY
 175 The
 176 .Nm serializer
 177 API first appeared in
 178 .Dx 1.3 .
 179 .Sh AUTHORS
 180 .An -nosplit
 181 The
 182 .Nm serializer
 183 API was written by
 184 .An Matt Dillon .
 185 This manual page was written by
 186 .An Hasso Tepper .