DragonFly On-Line Manual Pages

SERIALIZER(9)	      DragonFly Kernel Developer's Manual	 SERIALIZER(9)

NAME
     lwkt_serialize_init, lwkt_serialize_enter, lwkt_serialize_adaptive_enter,
     lwkt_serialize_try, lwkt_serialize_exit, lwkt_serialize_handler_enable,
     lwkt_serialize_handler_disable, lwkt_serialize_handler_call,
     lwkt_serialize_handler_try, ASSERT_SERIALIZED ASSERT_NOT_SERIALIZED --
     generic low level serializer

SYNOPSIS
     #include <sys/serialize.h>

     void
     lwkt_serialize_init(lwkt_serialize_t s);

     void
     lwkt_serialize_enter(lwkt_serialize_t s);

     void
     lwkt_serialize_adaptive_enter(lwkt_serialize_t s);

     int
     lwkt_serialize_try(lwkt_serialize_t s);

     void
     lwkt_serialize_exit(lwkt_serialize_t s);

     void
     lwkt_serialize_handler_enable(lwkt_serialize_t s);

     void
     lwkt_serialize_handler_disable(lwkt_serialize_t s);

     void
     lwkt_serialize_handler_call(lwkt_serialize_t s,
	 void (*func)(void *, void *), void *arg, void *frame);

     int
     lwkt_serialize_handler_try(lwkt_serialize_t s,
	 void (*func)(void *, void *), void *arg, void *frame);

     ASSERT_SERIALIZED(s);

     ASSERT_NOT_SERIALIZED(s);

DESCRIPTION
     The serializer API provides a fast locked-bus-cycle-based serialization
     facility that will serialize across blocking conditions.  It is very sim-
     ilar to a lock but much faster for the common case.

     This API was initially designed to be a replacement for SPL calls, but
     may be used whenever a low level exclusive lock (serialization) and/or
     interrupt/device interaction is required.	Unlike tokens this serializa-
     tion is not safe from deadlocks nor is it recursive, and care must be
     taken when using it.  Note that tsleep(9) will not release a serializer
     that is being held.

     There are two primary facilities -- the serializer facility itself and an
     integrated non-stackable interrupt handler disablement facility used by
     drivers.

     lwkt_serialize_init(), lwkt_serialize_enter() and lwkt_serialize_exit()
     respectively initialize, hold and release the serializer s.
     lwkt_serialize_try() is a non-blocking version of lwkt_serialize_enter().

     lwkt_serialize_adaptive_enter() is a special version of
     lwkt_serialize_enter() which will try to spin a bit before the current
     thread is put to sleep if the serializer s is contended.  By default,
     lwkt_serialize_adaptive_enter() favors spinning over sleeping.  This
     behavior can be changed by tuning the debug.serialize_bolimit and
     debug.serialize_boround sysctl(8) variables.  Note that
     lwkt_serialize_adaptive_enter() is only available in SMP kernels.

     lwkt_serialize_handler_disable(), lwkt_serialize_handler_enable() and
     lwkt_serialize_handler_call() respectively disable, enable and call an
     interrupt handler func for the serializer s.  The arguments arg and frame
     will be passed to the handler.  lwkt_serialize_handler_try() is a non-
     blocking version of lwkt_serialize_handler_call().

     The ASSERT_SERIALIZED() and ASSERT_NOT_SERIALIZED() macros assert that
     the serializer s is being held/not held.

RETURN VALUES
     The lwkt_serialize_try() and lwkt_serialize_handler_try() functions
     return 0 on success and 1 on failure.

FILES
     The serializer itself is implemented in /sys/kern/lwkt_serialize.c.  The
     header file /sys/sys/serialize.h describes the public interface and the
     structure of a serializer.

SEE ALSO
     crit_enter(9), spinlock(9), zsleep(9)

HISTORY
     The serializer API first appeared in DragonFly 1.3.

AUTHORS
     The serializer API was written by Matt Dillon.  This manual page was
     written by Hasso Tepper.

DragonFly 3.5			April 10, 2010			 DragonFly 3.5