man.bsd.lv manual page server

Manual Page Search Parameters
SERIALIZER(9) Kernel Developer's Manual SERIALIZER(9)

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, LWKT_SERIALIZE_INITIALIZER, ASSERT_SERIALIZED, ASSERT_NOT_SERIALIZEDgeneric low level serializer

#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);


LWKT_SERIALIZE_INITIALIZER; ASSERT_SERIALIZED(s);

ASSERT_NOT_SERIALIZED(s);

The serializer API provides a fast locked-bus-cycle-based serialization facility that will serialize across blocking conditions. It is very similar 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. If it is used by interrupt, callers should enter critical section to prevent the current thread holding the serializer being preempted by interrupt thread which may try to hold the same serializer. Unlike tokens this serialization 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.

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

() is a special version of () 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.

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

The macro LWKT_SERIALIZE_INITIALIZER evaluates to an initializer for the serializer.

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

The lwkt_serialize_handler_try() function return 0 on success and 1 on failure. The lwkt_serialize_try() function return 1 on success and 0 on failure.

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.

crit_enter(9), locking(9), spinlock(9), zsleep(9)

The serializer API first appeared in DragonFly 1.3.

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

January 17, 2014 DragonFly-5.6.1