Module Name: src
Committed By: rmind
Date: Fri Jan 8 12:12:49 UTC 2010
Modified Files:
src/share/man/man9: pcq.9
Log Message:
pcq(9): use more accurate wording, do not expose implementation details.
To generate a diff of this commit:
cvs rdiff -u -r1.2 -r1.3 src/share/man/man9/pcq.9
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/share/man/man9/pcq.9
diff -u src/share/man/man9/pcq.9:1.2 src/share/man/man9/pcq.9:1.3
--- src/share/man/man9/pcq.9:1.2 Mon Jan 4 23:06:34 2010
+++ src/share/man/man9/pcq.9 Fri Jan 8 12:12:49 2010
@@ -1,4 +1,4 @@
-.\" $NetBSD: pcq.9,v 1.2 2010/01/04 23:06:34 wiz Exp $
+.\" $NetBSD: pcq.9,v 1.3 2010/01/08 12:12:49 rmind Exp $
.\"
.\" Copyright (c) 2010 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -31,14 +31,8 @@
.Dt PCQ 9
.Os
.Sh NAME
-.Nm PCQ ,
-.Nm pcq_create ,
-.Nm pcq_destroy ,
-.Nm pcq_get ,
-.Nm pcq_maxitems ,
-.Nm pcq_peek ,
-.Nm pcq_put
-.Nd Producer/consumer queue
+.Nm pcq
+.Nd producer/consumer queue
.Sh SYNOPSIS
.In sys/pcq.h
.Ft pcq_t *
@@ -56,17 +50,16 @@
.Sh DESCRIPTION
The machine-independent
.Nm
-framework provides producer/consumer queues.
+interface provides lockless producer/consumer queues.
A queue
.Po
.Vt pcq_t
.Pc
allows multiple writers
-.Pq producers
+.Pq producers ,
but only a single reader
.Pq consumer .
-Compare-and-store operations are used to allow lockless updates.
-The consumer is expected to be protected by a mutex that covers
+The consumer is expected to be protected by a lock that covers
the structure that the
.Vt pcq_t
is embedded into
@@ -80,7 +73,7 @@
.Vt pcq_t
does not modify the item in any way.
.Nm
-does not prevent an item being inserted multiple times into a single
+does not prevent an item from being inserted multiple times into a single
.Vt pcq_t .
.Sh FUNCTIONS
.Bl -tag -width compact
@@ -93,13 +86,11 @@
.Dv KM_SLEEP ,
if
.Fn pcq_create
-should sleep until resources are available, or
+is allowed to sleep until resources are available, or
.Dv KM_NOSLEEP
if it should return
.Dv NULL
-if resources are unavailable.
-See
-.Xr kmem 9 .
+immediately, if resources are unavailable.
.It Fn pcq_destroy "pcq"
Free the resources held by
.Fa pcq .
@@ -127,17 +118,30 @@
The item must not have the value of
.Dv NULL .
.El
-.Sh FILES
-.Bl -tag -width sys/kern/subr_pcq.c
-.It Pa sys/kern/subr_pcq.c
+
+.Sh CODE REFERENCES
+This section describes places within the
+.Nx
+source tree where actual code implementing the
.Nm
-implementation.
-.El
+interface
+can be found.
+All pathnames are relative to
+.Pa /usr/src .
+.Pp
+The
+.Nm
+interface is implemented within the file
+.Pa sys/kern/subr_pcq.c .
.\" .Sh EXAMPLES
-.\" .Sh SEE ALSO
-.\" Cross-references should be ordered by section (low to high), then in
-.\" alphabetical order.
-.\" .Sh HISTORY
+.Sh SEE ALSO
+.Xr atomic_ops 3 ,
+.Xr queue 9
+.Sh HISTORY
+The
+.Nm
+interface first appeared in
+.Nx 6.0 .
.Sh AUTHORS
.An Matt Thomas Aq [email protected]
.\" .Sh CAVEATS
