/share/man/man9/mtx_pool.9

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 184 lines · 184 code · 0 blank · 0 comment · 0 complexity · f187ca2d39c808eb0f97cf7709161141 MD5 · raw file

  1. .\"
  2. .\" Copyright (C) 2002 Garrett Rooney <rooneg@electricjellyfish.net>.
  3. .\" 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. .\" 1. Redistributions of source code must retain the above copyright
  9. .\" notice(s), this list of conditions and the following disclaimer as
  10. .\" the first lines of this file unmodified other than the possible
  11. .\" addition of one or more copyright notices.
  12. .\" 2. Redistributions in binary form must reproduce the above copyright
  13. .\" notice(s), this list of conditions and the following disclaimer in the
  14. .\" documentation and/or other materials provided with the distribution.
  15. .\"
  16. .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
  17. .\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  18. .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  19. .\" DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY
  20. .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  21. .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
  22. .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
  23. .\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24. .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25. .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
  26. .\" DAMAGE.
  27. .\"
  28. .\" $FreeBSD$
  29. .\"
  30. .Dd February 6, 2010
  31. .Dt MTX_POOL 9
  32. .Os
  33. .Sh NAME
  34. .Nm mtx_pool ,
  35. .Nm mtx_pool_alloc ,
  36. .Nm mtx_pool_find ,
  37. .Nm mtx_pool_lock ,
  38. .Nm mtx_pool_lock_spin ,
  39. .Nm mtx_pool_unlock ,
  40. .Nm mtx_pool_unlock_spin ,
  41. .Nm mtx_pool_create ,
  42. .Nm mtx_pool_destroy
  43. .Nd "mutex pool routines"
  44. .Sh SYNOPSIS
  45. .In sys/param.h
  46. .In sys/lock.h
  47. .In sys/mutex.h
  48. .Ft "struct mtx *"
  49. .Fn mtx_pool_alloc "struct mtx_pool *pool"
  50. .Ft "struct mtx *"
  51. .Fn mtx_pool_find "struct mtx_pool *pool" "void *ptr"
  52. .Ft void
  53. .Fn mtx_pool_lock "struct mtx_pool *pool" "void *ptr"
  54. .Ft void
  55. .Fn mtx_pool_lock_spin "struct mtx_pool *pool" "void *ptr"
  56. .Ft void
  57. .Fn mtx_pool_unlock "struct mtx_pool *pool" "void *ptr"
  58. .Ft void
  59. .Fn mtx_pool_unlock_spin "struct mtx_pool *pool" "void *ptr"
  60. .Ft "struct mtx_pool *"
  61. .Fn mtx_pool_create "const char *mtx_name" "int pool_size" "int opts"
  62. .Ft "void"
  63. .Fn mtx_pool_destroy "struct mtx_pool **poolp"
  64. .Sh DESCRIPTION
  65. Mutex pools are designed to be used as short term leaf mutexes;
  66. i.e., the last mutex one might acquire before calling
  67. .Xr mtx_sleep 9 .
  68. They operate using a shared pool of mutexes.
  69. A mutex may be chosen from the pool based on a supplied pointer,
  70. which may or may not point to anything valid,
  71. or the caller may allocate an arbitrary shared mutex from the pool
  72. and save the returned mutex pointer for later use.
  73. .Pp
  74. The shared mutexes in the
  75. .Va mtxpool_sleep
  76. mutex pool,
  77. which is created by default,
  78. are standard, non-recursive,
  79. blockable mutexes, and should only be used in appropriate situations.
  80. The mutexes in the
  81. .Va mtxpool_lockbuilder
  82. mutex pool are similar, except that they are initialized with the MTX_NOWITNESS
  83. flag so that they may be used to build higher-level locks.
  84. Other mutex pools may be created that contain mutexes with different
  85. properties, such as spin mutexes.
  86. .Pp
  87. The caller can lock and unlock mutexes returned by the pool routines, but
  88. since the mutexes are shared, the caller should not attempt to destroy them
  89. or modify their characteristics.
  90. While pool mutexes are normally leaf mutexes
  91. (meaning that one cannot depend on any ordering guarantees
  92. after obtaining one),
  93. one can still obtain other mutexes under carefully controlled circumstances.
  94. Specifically, if one has a private mutex
  95. (one that was allocated and initialized by the caller),
  96. one can obtain it after obtaining a pool mutex if ordering issues are
  97. carefully accounted for.
  98. In these cases the private mutex winds up being the true leaf mutex.
  99. .Pp
  100. Pool mutexes have the following advantages:
  101. .Pp
  102. .Bl -enum -offset indent -compact
  103. .It
  104. No structural overhead;
  105. i.e., they can be associated with a structure without adding bloat to it.
  106. .It
  107. Mutexes can be obtained for invalid pointers, which is useful when one uses
  108. mutexes to interlock destructor operations.
  109. .It
  110. No initialization or destruction overhead.
  111. .It
  112. Can be used with
  113. .Xr mtx_sleep 9 .
  114. .El
  115. .Pp
  116. And the following disadvantages:
  117. .Pp
  118. .Bl -enum -offset indent -compact
  119. .It
  120. Should generally only be used as leaf mutexes.
  121. .It
  122. Pool/pool dependency ordering cannot be guaranteed.
  123. .It
  124. Possible L1 cache mastership contention between CPUs.
  125. .El
  126. .Pp
  127. .Fn mtx_pool_alloc
  128. obtains a shared mutex from the specified pool.
  129. This routine uses a simple rover to choose one of the shared mutexes managed
  130. by the
  131. .Nm
  132. subsystem.
  133. .Pp
  134. .Fn mtx_pool_find
  135. returns the shared mutex associated with the specified address.
  136. This routine will create a hash out of the pointer passed into it
  137. and will choose a shared mutex from the specified pool based on that hash.
  138. The pointer does not need to point to anything real.
  139. .Pp
  140. .Fn mtx_pool_lock ,
  141. .Fn mtx_pool_lock_spin ,
  142. .Fn mtx_pool_unlock ,
  143. and
  144. .Fn mtx_pool_unlock_spin
  145. lock and unlock the shared mutex from the specified pool
  146. associated with the specified address;
  147. they are a combination of
  148. .Fn mtx_pool_find
  149. and
  150. .Xr mtx_lock 9 ,
  151. .Xr mtx_lock_spin 9 ,
  152. .Xr mtx_unlock 9 ,
  153. and
  154. .Xr mtx_unlock_spin 9 ,
  155. respectively.
  156. Since these routines must first find the mutex to operate on,
  157. they are not as fast as directly using the mutex pointer returned by
  158. a previous invocation of
  159. .Fn mtx_pool_find
  160. or
  161. .Fn mtx_pool_alloc .
  162. .Pp
  163. .Fn mtx_pool_create
  164. allocates and initializes a new mutex pool of the
  165. specified size.
  166. The pool size must be a power of two.
  167. The
  168. .Fa opts
  169. argument is passed to
  170. .Xr mtx_init 9
  171. to set the options for each mutex in the pool.
  172. .Pp
  173. .Fn mtx_pool_destroy
  174. calls
  175. .Xr mtx_destroy 9
  176. on each mutex in the specified pool,
  177. deallocates the memory associated with the pool,
  178. and assigns NULL to the pool pointer.
  179. .Sh SEE ALSO
  180. .Xr locking 9 ,
  181. .Xr mutex 9
  182. .Sh HISTORY
  183. These routines first appeared in
  184. .Fx 5.0 .