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). Protected 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

Typical code fragment in the writer side:

    	mutex_enter(&writer_psz_lock);
    	/*
    	 * Perform the updates (e.g. remove data items from a list).
    	 */
    	...
    	pserialize_perform(object->psz);
    	/*
    	 * At this point it is safe to destroy old data items.
    	 */
    	mutex_exit(&writer_psz_lock);

# 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.

July 30, 2011 | NetBSD 5.99