pserialize(9) - NetBSD Manual Pages

PSERIALIZE(9)          NetBSD Kernel Developer's Manual          PSERIALIZE(9)


NAME
pserialize -- passive serialization mechanism
SYNOPSIS
#include <sys/pserialize.h> pserialize_t pserialize_create(void); void pserialize_destroy(pserialize_t psz); int pserialize_read_enter(void); void pserialize_read_exit(int s); void pserialize_perform(pserialize_t psz);
DESCRIPTION
Passive serialization is a reader / writer synchronisation mechanism designed for lock-less read operations. The read operations may happen from software interrupt at IPL_SOFTCLOCK.
FUNCTIONS
pserialize_create() Allocate a new synchronisation object. pserialize_destroy() Destroy the synchronisation object. No synchronisation activity should happen at this point. pserialize_read_enter() Enter the critical path of the reader side. Returns an IPL value, which must be passed to pserialize_read_exit(9). Pro- tected code path is not allowed to block. pserialize_read_exit() Exit the critical path of the reader side. Takes the IPL value returned by pserialize_read_enter(9). pserialize_perform() Perform the passive serialization on the writer side. Passing of this function ensures that no readers are in action. Writers must be additionally serialized with a separate mechanism, e.g. mutex(9). Operation blocks and it may only be performed from thread context.
EXAMPLES
Given a global database of frotz records: struct frotz { ... struct frotz *f_next; }; static struct { kmutex_t lock; pserialize_t psz; struct frotz *first; } frobbotzim __cacheline_aligned; Create a frotz and publish it, as a writer: struct frotz *f = pool_get(&frotz_pool, PR_WAITOK); /* Initialize f. */ ... mutex_enter(&frobbotzim.lock); f->f_next = frobbotzim.first; /* * Publish the contents of f->f_next before we publish the * pointer to f in frobbotzim.first. */ membar_producer(); frobbotzim.first = f; mutex_exit(&frobbotzim.lock); Find a frotz, as a reader: struct frotz *f; int error = ENOENT; int s; s = pserialize_read_enter(); for (f = frobbotzim.first; f != NULL; f = f->f_next) { /* Fetch f before we fetch anything f points to. */ membar_datadep_consumer(); if (f->f_... == key) { /* * Grab whatever part of the frotz we need. * Note that we can't use the frotz after * pserialize_read_exit, without a stronger * kind of reference, say a reference count * managed by atomic_ops(3). */ *resultp = f->f_...; error = 0; break; } } pserialize_read_exit(s); return error; Remove a frotz, as a writer, and free it once there are no more readers: struct frotz **fp, *f; mutex_enter(&frobbotzim.lock); for (fp = &frobbotzim.first; (f = *fp) != NULL; fp = &f->f_next) { if (f->f_... == key) { /* * Unhook it from the list. Readers may still * be traversing the list at this point, so * the next pointer must remain valid and * memory must remain allocated. */ *fp = f->f_next; break; } } /* * Wait for all existing readers to complete. New readers will * not see f because the list no longer points to it. */ pserialize_perform(frobbotzim.psz); /* Now nobody else can be touching f, so it is safe to free. */ mutex_exit(&frobbotzim.lock); if (f != NULL) pool_put(&frotz_pool, f);
CODE REFERENCES
The pserialize is implemented within the file sys/kern/subr_pserialize.c.
SEE ALSO
membar_ops(3), condvar(9), mutex(9), rwlock(9) Hennessy, et al., Passive serialization in a multitasking environment, US Patent and Trademark Office, US Patent 4809168, February 28, 1989.
HISTORY
Passive serialization mechanism first appeared in NetBSD 6.0. NetBSD 9.3 January 26, 2016 NetBSD 9.3

Powered by man-cgi (2024-08-26). Maintained for NetBSD by Kimmo Suominen. Based on man-cgi by Panagiotis Christias.