Re: svn commit: r333590 - head/share/man/man9

2018-06-25 Thread Matthew Macy 
On Mon, Jun 25, 2018 at 01:30 Andriy Gapon  wrote:

> On 25/06/2018 10:25, Ed Schouten wrote:
> > Hi Andriy, Matthew,
> >
> > 2018-06-24 23:36 GMT+02:00 Andriy Gapon :
> >> Perhaps a little application of google can help.
> >> [keywords: epoch based reclamation]
> >
> > Based on the man page, it wasn't clear that this refers to a generally
> > accepted construct or something that is specific to FreeBSD. Any
> > objections if I were to extend the man page as follows?
>
> Certainly not from me.
> Also, given that epoch(9) is a wrapper around (or based on) the
> implementation
> provided by Concurrency Kit, maybe we should have some kind of a gateway
> manual
> page for the latter.  That page would provide an introduction to
> Concurrency Kit
> and links to its resources.  Then epoch.9 could reference it.
>


There are man pages included with CK. Certain ports install them. For
reasons that he no longer recalls cognet chose to not install them. You'll
need to discuss it with him.

-M



> > Index: epoch.9
> > ===
> > --- epoch.9 (revision 335613)
> > +++ epoch.9 (working copy)
> > @@ -39,7 +39,7 @@
> >  .Nm epoch_wait ,
> >  .Nm epoch_call ,
> >  .Nm in_epoch ,
> > -.Nd kernel epoch based reclamation
> > +.Nd kernel Epoch Based Reclamation (EBR)
> >  .Sh SYNOPSIS
> >  .In sys/param.h
> >  .In sys/proc.h
> > @@ -191,3 +191,10 @@
> >  .Xr sleep 9 ,
> >  .Xr sx 9 ,
> >  .Xr timeout 9
> > +.Rs
> > +.%A K. Fraser
> > +.%T Practical lock-freedom
> > +.%D February 2004
> > +.%P 79-81
> > +.%U https://www.cl.cam.ac.uk/techreports/UCAM-CL-TR-579.pdf
> > +.Re
> >
>
>
> --
> Andriy Gapon
>
___
svn-src-head@freebsd.org mailing list
https://lists.freebsd.org/mailman/listinfo/svn-src-head
To unsubscribe, send any mail to "svn-src-head-unsubscr...@freebsd.org"

Re: svn commit: r333590 - head/share/man/man9

2018-06-25 Thread Andriy Gapon 
On 25/06/2018 10:25, Ed Schouten wrote:
> Hi Andriy, Matthew,
> 
> 2018-06-24 23:36 GMT+02:00 Andriy Gapon :
>> Perhaps a little application of google can help.
>> [keywords: epoch based reclamation]
> 
> Based on the man page, it wasn't clear that this refers to a generally
> accepted construct or something that is specific to FreeBSD. Any
> objections if I were to extend the man page as follows?

Certainly not from me.
Also, given that epoch(9) is a wrapper around (or based on) the implementation
provided by Concurrency Kit, maybe we should have some kind of a gateway manual
page for the latter.  That page would provide an introduction to Concurrency Kit
and links to its resources.  Then epoch.9 could reference it.

> Index: epoch.9
> ===
> --- epoch.9 (revision 335613)
> +++ epoch.9 (working copy)
> @@ -39,7 +39,7 @@
>  .Nm epoch_wait ,
>  .Nm epoch_call ,
>  .Nm in_epoch ,
> -.Nd kernel epoch based reclamation
> +.Nd kernel Epoch Based Reclamation (EBR)
>  .Sh SYNOPSIS
>  .In sys/param.h
>  .In sys/proc.h
> @@ -191,3 +191,10 @@
>  .Xr sleep 9 ,
>  .Xr sx 9 ,
>  .Xr timeout 9
> +.Rs
> +.%A K. Fraser
> +.%T Practical lock-freedom
> +.%D February 2004
> +.%P 79-81
> +.%U https://www.cl.cam.ac.uk/techreports/UCAM-CL-TR-579.pdf
> +.Re
> 


-- 
Andriy Gapon
___
svn-src-head@freebsd.org mailing list
https://lists.freebsd.org/mailman/listinfo/svn-src-head
To unsubscribe, send any mail to "svn-src-head-unsubscr...@freebsd.org"

Re: svn commit: r333590 - head/share/man/man9

2018-06-25 Thread Ed Schouten 
Hi Andriy, Matthew,

2018-06-24 23:36 GMT+02:00 Andriy Gapon :
> Perhaps a little application of google can help.
> [keywords: epoch based reclamation]

Based on the man page, it wasn't clear that this refers to a generally
accepted construct or something that is specific to FreeBSD. Any
objections if I were to extend the man page as follows?

Index: epoch.9
===
--- epoch.9 (revision 335613)
+++ epoch.9 (working copy)
@@ -39,7 +39,7 @@
 .Nm epoch_wait ,
 .Nm epoch_call ,
 .Nm in_epoch ,
-.Nd kernel epoch based reclamation
+.Nd kernel Epoch Based Reclamation (EBR)
 .Sh SYNOPSIS
 .In sys/param.h
 .In sys/proc.h
@@ -191,3 +191,10 @@
 .Xr sleep 9 ,
 .Xr sx 9 ,
 .Xr timeout 9
+.Rs
+.%A K. Fraser
+.%T Practical lock-freedom
+.%D February 2004
+.%P 79-81
+.%U https://www.cl.cam.ac.uk/techreports/UCAM-CL-TR-579.pdf
+.Re

-- 
Ed Schouten 
Nuxi, 's-Hertogenbosch, the Netherlands
___
svn-src-head@freebsd.org mailing list
https://lists.freebsd.org/mailman/listinfo/svn-src-head
To unsubscribe, send any mail to "svn-src-head-unsubscr...@freebsd.org"

Re: svn commit: r333590 - head/share/man/man9

2018-06-24 Thread Matthew Macy 
Sorry, I meant to respond.

http://concurrencykit.org/presentations/ebr.pdf

http://scalebsd.org/blog/2018/05/03/Why-is-munmap-single-threaded-and-what-can-we-do-about-it


http://scalebsd.org/blog/2018/06/16/UDP-and-epoch-for-liveness-guarantees


On Sun, Jun 24, 2018 at 13:56 Ed Schouten  wrote:

> Hi Matt,
>
> 2018-05-17 9:06 GMT+02:00 Ed Schouten :
> > Hi Matt,
> >
> > 2018-05-14 1:16 GMT+02:00 Matt Macy :
> >> +Epochs do not have any lock ordering issues. Entering and leaving
> >
> > It looks like the man page is missing some newlines between sentences.
> >
> > Quick question: How does this work relate to RCU
> > (https://en.wikipedia.org/wiki/Read-copy-update)? If there is any
> > relation, should we mention it in the documentation?
>
> I never got a response to this. Any thoughts?
>
> --
> Ed Schouten 
> Nuxi, 's-Hertogenbosch, the Netherlands
>
___
svn-src-head@freebsd.org mailing list
https://lists.freebsd.org/mailman/listinfo/svn-src-head
To unsubscribe, send any mail to "svn-src-head-unsubscr...@freebsd.org"

Re: svn commit: r333590 - head/share/man/man9

2018-06-24 Thread Andriy Gapon 
On 24/06/2018 23:55, Ed Schouten wrote:
> Hi Matt,
> 
> 2018-05-17 9:06 GMT+02:00 Ed Schouten :
>> Hi Matt,
>>
>> 2018-05-14 1:16 GMT+02:00 Matt Macy :
>>> +Epochs do not have any lock ordering issues. Entering and leaving
>>
>> It looks like the man page is missing some newlines between sentences.
>>
>> Quick question: How does this work relate to RCU
>> (https://en.wikipedia.org/wiki/Read-copy-update)? If there is any
>> relation, should we mention it in the documentation?
> 
> I never got a response to this. Any thoughts?

Perhaps a little application of google can help.
[keywords: epoch based reclamation]

-- 
Andriy Gapon
___
svn-src-head@freebsd.org mailing list
https://lists.freebsd.org/mailman/listinfo/svn-src-head
To unsubscribe, send any mail to "svn-src-head-unsubscr...@freebsd.org"

Re: svn commit: r333590 - head/share/man/man9

2018-06-24 Thread Ed Schouten 
Hi Matt,

2018-05-17 9:06 GMT+02:00 Ed Schouten :
> Hi Matt,
>
> 2018-05-14 1:16 GMT+02:00 Matt Macy :
>> +Epochs do not have any lock ordering issues. Entering and leaving
>
> It looks like the man page is missing some newlines between sentences.
>
> Quick question: How does this work relate to RCU
> (https://en.wikipedia.org/wiki/Read-copy-update)? If there is any
> relation, should we mention it in the documentation?

I never got a response to this. Any thoughts?

-- 
Ed Schouten 
Nuxi, 's-Hertogenbosch, the Netherlands
___
svn-src-head@freebsd.org mailing list
https://lists.freebsd.org/mailman/listinfo/svn-src-head
To unsubscribe, send any mail to "svn-src-head-unsubscr...@freebsd.org"

Re: svn commit: r333590 - head/share/man/man9

2018-05-17 Thread Ed Schouten 
Hi Matt,

2018-05-14 1:16 GMT+02:00 Matt Macy :
> +Epochs do not have any lock ordering issues. Entering and leaving

It looks like the man page is missing some newlines between sentences.

Quick question: How does this work relate to RCU
(https://en.wikipedia.org/wiki/Read-copy-update)? If there is any
relation, should we mention it in the documentation?

-- 
Ed Schouten 
Nuxi, 's-Hertogenbosch, the Netherlands
___
svn-src-head@freebsd.org mailing list
https://lists.freebsd.org/mailman/listinfo/svn-src-head
To unsubscribe, send any mail to "svn-src-head-unsubscr...@freebsd.org"

svn commit: r333590 - head/share/man/man9

2018-05-13 Thread Matt Macy 
Author: mmacy
Date: Sun May 13 23:16:04 2018
New Revision: 333590
URL: https://svnweb.freebsd.org/changeset/base/333590

Log:
  Add epoch(9) man page
  
  Reviewed by:  gallatin@
  Approved by:  sbruno@

Added:
  head/share/man/man9/epoch.9   (contents, props changed)
Modified:
  head/share/man/man9/Makefile

Modified: head/share/man/man9/Makefile
==
--- head/share/man/man9/MakefileSun May 13 23:04:35 2018
(r333589)
+++ head/share/man/man9/MakefileSun May 13 23:16:04 2018
(r333590)
@@ -123,6 +123,7 @@ MAN=accept_filter.9 \
drbr.9 \
driver.9 \
DRIVER_MODULE.9 \
+   epoch.9 \
EVENTHANDLER.9 \
eventtimers.9 \
extattr.9 \

Added: head/share/man/man9/epoch.9
==
--- /dev/null   00:00:00 1970   (empty, because file is newly added)
+++ head/share/man/man9/epoch.9 Sun May 13 23:16:04 2018(r333590)
@@ -0,0 +1,161 @@
+.\"
+.\" Copyright (C) 2018 Matthew Macy . 
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"notice(s), this list of conditions and the following disclaimer as
+.\"the first lines of this file unmodified other than the possible
+.\"addition of one or more copyright notices.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"notice(s), this list of conditions and the following disclaimer in the
+.\"documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
+.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+.\" DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY
+.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
+.\" DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd May 13, 2018
+.Dt EPOCH 9
+.Os
+.Sh NAME
+.Nm epoch ,
+.Nm epoch_context ,
+.Nm epoch_alloc ,
+.Nm epoch_free ,
+.Nm epoch_enter ,
+.Nm epoch_exit ,
+.Nm epoch_wait ,
+.Nm epoch_call ,
+.Nm in_epoch ,
+.Nd kernel epoch based reclaimation
+.Sh SYNOPSIS
+.In sys/param.h
+.In sys/proc.h
+.In sys/epoch.h
+.Ft epoch_t
+.Fn epoch_alloc "void"
+.Ft void
+.Fn epoch_enter "epoch_t epoch"
+.Ft void
+.Fn epoch_exit "epoch_t epoch"
+.Ft void
+.Fn epoch_wait "epoch_t epoch"
+.Ft void
+.Fn epoch_call "epoch_t epoch" "epoch_context_t ctx" "void (*callback) 
(epoch_context_t)"
+.Ft int
+.Fn in_epoch "void"
+.Sh DESCRIPTION
+Epochs are used to guarantee liveness and immutability of data by
+deferring reclamation and mutation until a grace period has elapsed.
+Epochs do not have any lock ordering issues. Entering and leaving
+an epoch section will never block.
+.Pp
+Epochs are allocated with
+.Fn epoch_alloc
+and freed with
+.Fn epoch_free .
+Threads indicate the start of an epoch critical section by calling
+.Fn epoch_enter .
+The end of a critical section is indicated by calling
+.Fn epoch_exit .
+A thread can wait until a grace period has elapsed
+since any threads have entered
+the epoch by calling
+.Fn epoch_wait .
+If the thread can't sleep or is otherwise in a performance sensitive
+path it can ensure that a grace period has elapsed by calling
+.Fn epoch_call
+with a callback with any work that needs to wait for an epoch to elapse.
+Only non-sleepable locks can be acquired during a section protected by
+.Fn epoch_enter
+and
+.Fn epoch_exit .
+INVARIANTS can assert that a thread is in an epoch by using
+.Fn in_epoch .
+.Pp
+The epoch API currently does not support sleeping in epoch sections.
+A caller cannot do epoch_enter recursively on different epochs. A
+caller should never call
+.Fn epoch_wait
+in the middle of an epoch section as this will lead to a deadlock.
+.Pp
+Note that epochs are not a straight replacement for read locks. Callers
+must use safe list and tailq traversal routines in an epoch (see ck_queue).
+When modifying a list referenced from an epoch section safe removal
+routines must be used and the caller can no longer modify a list entry
+in place. An item to be modified must be handled with copy on write
+and frees must be deferred until after a grace period has elapsed.
+
+.Sh RETURN VALUES
+.Fn in_epoch
+will return 1 if curthread