Commit Graph

53 Commits

Author SHA1 Message Date
Mateusz Guzik
ea0a0939ef sx: fix up manpage after r363113
No date change as there is no new information.

Submitted by:	sigsys@gmail.com
Differential Revision: https://reviews.freebsd.org/D26341
2020-09-05 20:22:02 +00:00
Mateusz Guzik
bd3cbfd26f sx: remove SX_NOADAPTIVE from the man page
The flag itself was removed in r341593
2020-07-11 21:57:43 +00:00
Mark Johnston
755230eb9f Clean up the SYSINIT_FLAGS definitions for rwlock(9) and rmlock(9).
Avoid duplication in their macro definitions, and document them. No
functional change intended.

MFC after:	1 week
2017-11-21 14:59:23 +00:00
Bryan Drewery
a23b48fee5 Reword descriptions of asserting locks held without WITNESS.
This corrects an error in r296947 in that it is not possible to assert
which thread holds a shared (or read) lock, but it is possible to assert
that one is held.  Just not very useful.

MFC after:	1 week
Submitted by:	wblock, jhb
Reviewed by:	kib (earlier version), jhb, wblock
Sponsored by:	EMC / Isilon Storage Division
Differential Revision:	https://reviews.freebsd.org/D5659
2016-03-29 16:07:51 +00:00
Bryan Drewery
4d8ece19ae Remove incorrect BUGS entry about asserting lock not held.
For non-WITNESS< assertion support for SA_UNLOCKED was added in r125421 and
made to panic in r126316.

MFC after:	1 week
2016-03-16 18:39:48 +00:00
Bryan Drewery
6ccfaffdd1 Reword SX_NOADAPTIVE description to be clear that adaptive is default.
The default changed in r193011.

MFC after:	 1 week
2016-03-14 00:51:45 +00:00
Dmitry Chagin
9972df7d13 Properly sort Xr to silence mandoc warnings.
Differential Revision:	https://reviews.freebsd.org/D1314
Reviewed by:	wblock
MFC after:	1 Month
2014-12-15 20:48:06 +00:00
Dmitry Chagin
fd07ddcf6f Add _NEW flag to mtx(9), sx(9), rmlock(9) and rwlock(9).
A _NEW flag passed to _init_flags() to avoid check for double-init.

Differential Revision:	https://reviews.freebsd.org/D1208
Reviewed by:	jhb, wblock
MFC after:	1 Month
2014-12-13 21:00:10 +00:00
Pawel Jakub Dawidek
d576deedb5 Constify arguments for locking KPIs where possible.
This enables locking consumers to pass their own structures around as const and
be able to assert locks embedded into those structures.

Reviewed by:	ed, kib, jhb
2011-11-16 21:51:17 +00:00
Attilio Rao
1ae1c2a3bd Reverse the logic for ADAPTIVE_SX option and enable it by default.
Introduce for this operation the reverse NO_ADAPTIVE_SX option.
The flag SX_ADAPTIVESPIN to be passed to sx_init_flags(9) gets suppressed
and the new flag, offering the reversed logic, SX_NOADAPTIVE is added.

Additively implements adaptive spininning for sx held in shared mode.
The spinning limit can be handled through sysctls in order to be tuned
while the code doesn't reach the release, after which time they should
be dropped probabilly.

This change has made been necessary by recent benchmarks where it does
improve concurrency of workloads in presence of high contention
(ie. ZFS).

KPI breakage is documented by __FreeBSD_version bumping, manpage and
UPDATING updates.

Requested by:	jeff, kmacy
Reviewed by:	jeff
Tested by:	pho
2009-05-29 01:49:27 +00:00
Christian Brueffer
23ae24e09a Bump .Dd for previous revision. 2007-11-26 15:21:21 +00:00
Attilio Rao
0e933b2f3c Update sx(9) lock manpage in order to add missing prototypes for function
sx_slock_sig() and sx_xlock_sig() and their respective explanation.
2007-11-25 01:55:53 +00:00
John Baldwin
7ec137e5b0 Rename the macros for assertion flags passed to sx_assert() from SX_* to
SA_* to match mutexes and rwlocks.  The old flags still exist for
backwards compatiblity.

Requested by:	attilio
2007-05-19 21:26:05 +00:00
John Baldwin
2b9573af36 Document sx_xholder(). 2007-05-19 20:24:32 +00:00
John Baldwin
e45907c90e Document SX_RECURSE flag. 2007-05-19 16:38:10 +00:00
John Baldwin
4e7f640dfb Optimize sx locks to use simple atomic operations for the common cases of
obtaining and releasing shared and exclusive locks.  The algorithms for
manipulating the lock cookie are very similar to that rwlocks.  This patch
also adds support for exclusive locks using the same algorithm as mutexes.

A new sx_init_flags() function has been added so that optional flags can be
specified to alter a given locks behavior.  The flags include SX_DUPOK,
SX_NOWITNESS, SX_NOPROFILE, and SX_QUITE which are all identical in nature
to the similar flags for mutexes.

Adaptive spinning on select locks may be enabled by enabling the
ADAPTIVE_SX kernel option.  Only locks initialized with the SX_ADAPTIVESPIN
flag via sx_init_flags() will adaptively spin.

The common cases for sx_slock(), sx_sunlock(), sx_xlock(), and sx_xunlock()
are now performed inline in non-debug kernels.  As a result, <sys/sx.h> now
requires <sys/lock.h> to be included prior to <sys/sx.h>.

The new kernel option SX_NOINLINE can be used to disable the aforementioned
inlining in non-debug kernels.

The size of struct sx has changed, so the kernel ABI is probably greatly
disturbed.

MFC after:	1 month
Submitted by:	attilio
Tested by:	kris, pjd
2007-03-31 23:23:42 +00:00
Julian Elischer
a280550abf Add some cross references to locking.9 from related pages. 2007-03-30 18:07:26 +00:00
John Baldwin
e7573e7ad7 Allow threads to atomically release rw and sx locks while waiting for an
event.  Locking primitives that support this (mtx, rw, and sx) now each
include their own foo_sleep() routine.
- Rename msleep() to _sleep() and change it's 'struct mtx' object to a
  'struct lock_object' pointer.  _sleep() uses the recently added
  lc_unlock() and lc_lock() function pointers for the lock class of the
  specified lock to release the lock while the thread is suspended.
- Add wrappers around _sleep() for mutexes (mtx_sleep()), rw locks
  (rw_sleep()), and sx locks (sx_sleep()).  msleep() still exists and
  is now identical to mtx_sleep(), but it is deprecated.
- Rename SLEEPQ_MSLEEP to SLEEPQ_SLEEP.
- Rewrite much of sleep.9 to not be msleep(9) centric.
- Flesh out the 'RETURN VALUES' section in sleep.9 and add an 'ERRORS'
  section.
- Add __nonnull(1) to _sleep() and msleep_spin() so that the compiler will
  warn if you try to pass a NULL wait channel.  The functions already have
  a KASSERT to that effect.
2007-03-09 22:41:01 +00:00
John Baldwin
cc61ffc3fb - Sort functions in the order that rwlock(9) and mutex(9) use.
- Markup sx_unlock() as a function rather than saying it is a macro.
  The macro part is an implementation detail, and all the other sx_*lock()
  functions are actually macros, too.
- Use the same style as rwlock(9) and mutex(9) to markup sx_assert() and
  SX_SYSINIT() with respect to headers and kernel options.
- Add a missing MLINK.
2007-03-09 16:52:26 +00:00
Pawel Jakub Dawidek
d8e7058159 Document sx_xlocked(9).
Submitted by:	ssouhlal
2006-07-12 15:40:35 +00:00
John Baldwin
9fc7158c3c Trim a couple of xrefs. 2006-04-19 20:41:56 +00:00
Gleb Smirnoff
38fdbc1679 Xref rwlock(9).
Reviewed by:	ru
2006-02-01 20:30:55 +00:00
Ruslan Ermilov
c0854fb7b2 Scheduled mdoc(7) sweep. 2005-01-12 21:48:25 +00:00
Giorgos Keramidas
b762042dce Make an attempt at explaining why sx(9) locks cannot be safely obtained
after acquiring a mutex(9).

PR:		docs/75571
Submitted by:	darrenr
Explanation by:	jhb
2005-01-05 22:04:12 +00:00
Darren Reed
52865ee591 Document that sx_unlock() exists as a macro.
Remove redundant include file, <sys/kernel.h>, and clean up the function
list at the top with the addition of a "Sx utility macro" section.
2004-07-11 16:08:25 +00:00
Ruslan Ermilov
bf7f20c2b6 Assorted markup, spelling, and grammar fixes. 2004-06-16 08:33:57 +00:00
John Baldwin
ab9fe4e1fe - Clarify ambiguous statement about not being able to both slock and xlock
a single lock at the same time.
- Avoid using "own" to refer to holding either a shared or exclusive lock
  as it is only really correct for exclusive locks.
- Reword the sentence about sleep-ability to read easier.

Requested by:	truckman (1)
2004-02-24 21:36:39 +00:00
Pawel Jakub Dawidek
8d719eb22e Document new 'what' value for sx_assert(9).
PS. There is a inconsistency in this manual page, because in
    non-WITNESS case sx_assert(9) does not panics, it only prints
    the warning. I haven't fixed this, because jhb@ is planing to
    replace those printf()s with panic()s.

Reviewed by:	jhb
Approved by:	jhb, scottl (mentor)
2004-02-04 08:24:05 +00:00
Joseph Koshy
de77c1ba47 Add "options INVARIANTS" and "options INVARIANT_SUPPORT" to the
synopsis, with supporting text in the body of the manual page.

Add a cross-reference to panic(9) for completeness.

Reviewed by:	ru (synopsis changes)
2004-01-01 05:16:35 +00:00
Joseph Koshy
6c0f2b530e Make this manual page reflect the sources better.
- A #include of <sys/mutex.h> is no longer needed to use sx(9) (since
  2001/05/01).
- Use of the SX_SYSINIT() macro requires inclusion of '<sys/kernel.h>'
2003-12-28 01:37:48 +00:00
Joseph Koshy
2d8d6274dc Improve continuity of text. 2003-12-27 14:01:08 +00:00
Ruslan Ermilov
959d6c24f6 Get rid of duplicates. 2003-09-14 13:41:59 +00:00
Hartmut Brandt
33f73ee488 Document the fact that one is allowed to sleep while holding an sx lock.
Discussed with: jhb@
2003-06-12 09:06:25 +00:00
Ruslan Ermilov
5ec37969a1 mdoc(7) police: lint. 2002-05-29 18:00:23 +00:00
Bill Fenner
04df644c95 mdoc police: turn .PP back into .Pp 2002-04-17 21:26:43 +00:00
Chad David
55d04e913a Update the .Fn line for SX_SYSINIT to include the parameter types. 2002-04-12 03:55:43 +00:00
Andrew R. Reiter
80cc42da6b - Add notes about SX_SYSINIT and MTX_SYSINIT in order to document the
recent additions of these macros.
- Add in a MLINK to create SX_SYSINIT.9 and MTX_SYSINIT.9.
2002-04-02 17:21:00 +00:00
Dima Dorfman
a254506ee5 Add mtx_pool(9) to the SEE ALSO section.
Submitted by:	Garrett Rooney <rooneg@electricjellyfish.net>
2002-03-28 12:51:06 +00:00
Ruslan Ermilov
5f6a3b99a1 mdoc(7) police: WITNESS is a #define, mark it as such. 2001-11-21 11:47:55 +00:00
Ruslan Ermilov
d1919ca628 mdoc(7) police: cosmetique. 2001-11-21 11:44:36 +00:00
John Baldwin
7fe151bee5 Document sx_assert(9). 2001-10-23 22:51:59 +00:00
Bruce Evans
6ea8d9af05 Fixed wrong include in synopsis. 2001-10-04 09:01:49 +00:00
Ruslan Ermilov
32eef9aeb1 mdoc(7) police: Use the new .In macro for #include statements. 2001-10-01 16:09:29 +00:00
Mike Silbersack
42e5dee992 Common Mike adds see alsos from all of the synchronization
man pages to their brethren.
2001-09-17 07:24:48 +00:00
Ruslan Ermilov
135047c346 mdoc(7) police: bump document date. 2001-08-14 16:01:00 +00:00
Jason Evans
f72a2ca28c Add missing commas. 2001-08-14 05:10:07 +00:00
Jason Evans
d55229b72e Add sx_try_upgrade() and sx_downgrade().
Submitted by:	Alexander Kabaev <ak03@gte.com>
2001-08-13 21:25:30 +00:00
Ruslan Ermilov
c5e7e03a14 Spell "FreeBSD" with "F" and "BSD" in uppercase. 2001-08-13 16:33:00 +00:00
Jason Evans
920ae52d67 Document sx_try_[sx]lock(). 2001-08-07 04:29:53 +00:00
Jens Schweikhardt
c1f3e4bf21 Removed whitespace at end-of-line; no content changes. I simply did
cd src/share; find man[1-9] -type f|xargs perl -pi -e 's/[ \t]+$//'

BTW, what editors are the culprits? I'm using vim and it shows
me whitespace at EOL in troff files with a thick blue block...

Reviewed by:	Silence from cvs diff -b
MFC after:	7 days
2001-07-14 19:41:16 +00:00