Samy Al Bahra
13 years ago
parent
ce7278140c
commit
68a1465536
@ -0,0 +1,118 @@
|
||||
.\"
|
||||
.\" Copyright 2012 Samy Al Bahra.
|
||||
.\" All rights reserved.
|
||||
.\"
|
||||
.\" 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, this list of conditions and the following disclaimer.
|
||||
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||||
.\" notice, 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 REGENTS AND CONTRIBUTORS ``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 REGENTS OR CONTRIBUTORS 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.
|
||||
.\"
|
||||
.\"
|
||||
.Dd September 2, 2012
|
||||
.Dt CK_EPOCH_BARRIER 3
|
||||
.Sh NAME
|
||||
.Nm ck_epoch_barrier
|
||||
.Nd block until a grace period and all callbacks have been dispatched
|
||||
.Sh LIBRARY
|
||||
Concurrency Kit (libck, \-lck)
|
||||
.Sh SYNOPSIS
|
||||
.In ck_epoch.h
|
||||
.Ft void
|
||||
.Fn ck_epoch_barrier "ck_epoch_t *epoch" "ck_epoch_record_t *record"
|
||||
.Sh DESCRIPTION
|
||||
The
|
||||
.Fn ck_epoch_barrier 3
|
||||
function will block the caller until a grace period has been
|
||||
detected, according to the semantics of epoch reclamation.
|
||||
Any objects requiring safe memory reclamation which are logically
|
||||
deleted are safe for physical deletion following a call to
|
||||
.Fn ck_epoch_barrier 3 . This function will also dispatch all callbacks
|
||||
associated with
|
||||
.Fa epoch
|
||||
that were previously scheduled via
|
||||
.Fn ck_epoch_call 3 .
|
||||
.Sh EXAMPLE
|
||||
.Bd -literal -offset indent
|
||||
|
||||
#include <ck_epoch.h>
|
||||
#include <ck_stack.h>
|
||||
#include <stdlib.h>
|
||||
|
||||
/*
|
||||
* epoch was previously initialized with ck_epoch_init.
|
||||
* stack was previously initialized with ck_stack_init.
|
||||
*/
|
||||
ck_epoch_t *epoch;
|
||||
ck_stack_t *stack;
|
||||
|
||||
void
|
||||
function(void)
|
||||
{
|
||||
ck_epoch_record_t *record;
|
||||
ck_stack_entry_t *s;
|
||||
|
||||
record = malloc(sizeof *record);
|
||||
ck_epoch_register(&epoch, record);
|
||||
|
||||
/*
|
||||
* We are using an epoch section here to guarantee no
|
||||
* nodes in the stack are deleted while we are dereferencing
|
||||
* them. This is needed here because there are multiple writers.
|
||||
* If there was only one thread popping from the this stack,
|
||||
* then there is no need to ck_epoch_begin/ck_epoch_end.
|
||||
*/
|
||||
ck_epoch_begin(epoch, record);
|
||||
|
||||
/* Logically delete an object. */
|
||||
s = ck_stack_pop_upmc(stack);
|
||||
|
||||
ck_epoch_end(epoch, record);
|
||||
|
||||
/*
|
||||
* Wait until no threads could possibly have a reference to the
|
||||
* object we just popped (assume all threads are simply executing
|
||||
* ck_stack_pop_upmc).
|
||||
*/
|
||||
ck_epoch_barrier(epoch, record);
|
||||
|
||||
/* It is now safe to physically delete the object. */
|
||||
free(s);
|
||||
return;
|
||||
}
|
||||
.Sh RETURN VALUES
|
||||
This function has no return value.
|
||||
.Sh ERRORS
|
||||
Behavior is undefined if the object pointed to by
|
||||
.Fa epoch
|
||||
is not a valid epoch object. The object pointed to by
|
||||
.Fa record
|
||||
must have been previously registered via
|
||||
.Fn ck_epoch_register 3 .
|
||||
.Sh SEE ALSO
|
||||
.Xr ck_epoch_init 3 ,
|
||||
.Xr ck_epoch_register 3 ,
|
||||
.Xr ck_epoch_unregister 3 ,
|
||||
.Xr ck_epoch_recycle 3 ,
|
||||
.Xr ck_epoch_poll 3 ,
|
||||
.Xr ck_epoch_synchronize 3 ,
|
||||
.Xr ck_epoch_call 3 ,
|
||||
.Xr ck_epoch_begin 3 ,
|
||||
.Xr ck_epoch_end 3
|
||||
.Pp
|
||||
Additional information available at http://concurrencykit.org/
|
||||
@ -0,0 +1,71 @@
|
||||
.\"
|
||||
.\" Copyright 2012 Samy Al Bahra.
|
||||
.\" All rights reserved.
|
||||
.\"
|
||||
.\" 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, this list of conditions and the following disclaimer.
|
||||
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||||
.\" notice, 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 REGENTS AND CONTRIBUTORS ``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 REGENTS OR CONTRIBUTORS 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.
|
||||
.\"
|
||||
.\"
|
||||
.Dd September 2, 2012
|
||||
.Dt CK_EPOCH_BEGIN 3
|
||||
.Sh NAME
|
||||
.Nm ck_epoch_begin
|
||||
.Nd begin epoch-protected segment of execution
|
||||
.Sh LIBRARY
|
||||
Concurrency Kit (libck, \-lck)
|
||||
.Sh SYNOPSIS
|
||||
.In ck_epoch.h
|
||||
|
||||
.Ft void
|
||||
.Fn ck_epoch_begin "ck_epoch_t *epoch" "ck_epoch_record_t *record"
|
||||
.Sh DESCRIPTION
|
||||
The
|
||||
.Fn ck_epoch_begin 3
|
||||
function will mark the beginning of an epoch-protected code section.
|
||||
An epoch-protected code section is delimited by a call to the
|
||||
.Fn ck_epoch_end 3
|
||||
function. Though recursion is allowed for epoch-protected sections,
|
||||
recursive calls will be associated with the
|
||||
.Fn ck_epoch_begin 3
|
||||
that is at the top of the call stack.
|
||||
.Sh RETURN VALUES
|
||||
This function has no return value.
|
||||
.Sh ERRORS
|
||||
The object pointed to by
|
||||
.Fa epoch
|
||||
must have been previously initiated via
|
||||
.Fn ck_epoch_init 3 .
|
||||
The object pointed to by
|
||||
.Fa record
|
||||
must have been previously registered via
|
||||
.Fn ck_epoch_register 3 .
|
||||
.Sh SEE ALSO
|
||||
.Xr ck_epoch_init 3 ,
|
||||
.Xr ck_epoch_register 3 ,
|
||||
.Xr ck_epoch_unregister 3 ,
|
||||
.Xr ck_epoch_recycle 3 ,
|
||||
.Xr ck_epoch_poll 3 ,
|
||||
.Xr ck_epoch_synchronize 3 ,
|
||||
.Xr ck_epoch_barrier 3 ,
|
||||
.Xr ck_epoch_call 3 ,
|
||||
.Xr ck_epoch_end 3
|
||||
.Pp
|
||||
Additional information available at http://concurrencykit.org/
|
||||
@ -0,0 +1,133 @@
|
||||
.\"
|
||||
.\" Copyright 2012 Samy Al Bahra.
|
||||
.\" All rights reserved.
|
||||
.\"
|
||||
.\" 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, this list of conditions and the following disclaimer.
|
||||
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||||
.\" notice, 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 REGENTS AND CONTRIBUTORS ``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 REGENTS OR CONTRIBUTORS 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.
|
||||
.\"
|
||||
.\"
|
||||
.Dd September 2, 2012
|
||||
.Dt CK_EPOCH_CALL 3
|
||||
.Sh NAME
|
||||
.Nm ck_epoch_call
|
||||
.Nd defer function execution until a grace period
|
||||
.Sh LIBRARY
|
||||
Concurrency Kit (libck, \-lck)
|
||||
.Sh SYNOPSIS
|
||||
.In ck_epoch.h
|
||||
|
||||
typedef struct ck_epoch_entry ck_epoch_entry_t;
|
||||
|
||||
typedef void ck_epoch_cb_t(ck_epoch_entry_t *);
|
||||
.Ft void
|
||||
.Fn ck_epoch_call "ck_epoch_record_t *record" "ck_epoch_entry_t *entry" "ck_epoch_cb_t *function"
|
||||
.Sh DESCRIPTION
|
||||
The
|
||||
.Fn ck_epoch_call 3
|
||||
function will defer the execution of the function pointed to by
|
||||
.Fa function
|
||||
until a grace-period has been detected. The function will be provided
|
||||
the pointer specified by
|
||||
.Fa entry .
|
||||
The function will execute at some time in the future via calls to
|
||||
.Fn ck_epoch_synchronize 3 ,
|
||||
.Fn ck_epoch_barrier 3
|
||||
or
|
||||
.Fn ck_epoch_poll 3 .
|
||||
.Sh EXAMPLE
|
||||
.Bd -literal -offset indent
|
||||
|
||||
#include <ck_epoch.h>
|
||||
#include <ck_stack.h>
|
||||
#include <stdlib.h>
|
||||
|
||||
/*
|
||||
* epoch was previously initialized with ck_epoch_init.
|
||||
*/
|
||||
ck_epoch_t *epoch;
|
||||
|
||||
struct object {
|
||||
int value;
|
||||
ck_epoch_entry_t epoch_entry;
|
||||
};
|
||||
static struct object *global;
|
||||
|
||||
CK_EPOCH_CONTAINER(struct object, epoch_entry, object_container)
|
||||
|
||||
void
|
||||
destroy_object(ck_epoch_entry_t *e)
|
||||
{
|
||||
struct object *o = object_container(e);
|
||||
|
||||
free(o);
|
||||
return;
|
||||
}
|
||||
|
||||
void
|
||||
function(void)
|
||||
{
|
||||
ck_epoch_record_t *record;
|
||||
struct object *n;
|
||||
|
||||
record = malloc(sizeof *record);
|
||||
ck_epoch_register(&epoch, record);
|
||||
|
||||
n = malloc(sizeof *n);
|
||||
if (n == NULL)
|
||||
return;
|
||||
|
||||
n->value = 1;
|
||||
|
||||
/*
|
||||
* We are using an epoch section here because there are multiple
|
||||
* writers. It is also an option to use other forms of blocking
|
||||
* write-side synchronization such as mutexes.
|
||||
*/
|
||||
ck_epoch_begin(epoch, record);
|
||||
n = ck_pr_fas_ptr(&global, n);
|
||||
ck_epoch_end(epoch, record);
|
||||
|
||||
/* Defer destruction of previous object. */
|
||||
ck_epoch_call(record, &n->epoch_entry, destroy_object);
|
||||
|
||||
/* Poll epoch sub-system in non-blocking manner. */
|
||||
ck_epoch_poll(&epoch, record);
|
||||
return;
|
||||
}
|
||||
.Sh RETURN VALUES
|
||||
This function has no return value.
|
||||
.Sh ERRORS
|
||||
The object pointed to by
|
||||
.Fa record
|
||||
must have been previously registered via
|
||||
.Fn ck_epoch_register 3 .
|
||||
.Sh SEE ALSO
|
||||
.Xr ck_epoch_init 3 ,
|
||||
.Xr ck_epoch_register 3 ,
|
||||
.Xr ck_epoch_unregister 3 ,
|
||||
.Xr ck_epoch_recycle 3 ,
|
||||
.Xr ck_epoch_poll 3 ,
|
||||
.Xr ck_epoch_synchronize 3 ,
|
||||
.Xr ck_epoch_barrier 3 ,
|
||||
.Xr ck_epoch_begin 3 ,
|
||||
.Xr ck_epoch_end 3
|
||||
.Pp
|
||||
Additional information available at http://concurrencykit.org/
|
||||
@ -0,0 +1,65 @@
|
||||
.\"
|
||||
.\" Copyright 2012 Samy Al Bahra.
|
||||
.\" All rights reserved.
|
||||
.\"
|
||||
.\" 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, this list of conditions and the following disclaimer.
|
||||
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||||
.\" notice, 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 REGENTS AND CONTRIBUTORS ``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 REGENTS OR CONTRIBUTORS 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.
|
||||
.\"
|
||||
.\"
|
||||
.Dd September 2, 2012
|
||||
.Dt CK_EPOCH_END 3
|
||||
.Sh NAME
|
||||
.Nm ck_epoch_end
|
||||
.Nd end epoch-protected segment of execution
|
||||
.Sh LIBRARY
|
||||
Concurrency Kit (libck, \-lck)
|
||||
.Sh SYNOPSIS
|
||||
.In ck_epoch.h
|
||||
|
||||
.Ft void
|
||||
.Fn ck_epoch_end "ck_epoch_t *epoch" "ck_epoch_record_t *record"
|
||||
.Sh DESCRIPTION
|
||||
The
|
||||
.Fn ck_epoch_end 3
|
||||
function will mark the end of an epoch-protected code section.
|
||||
.Sh RETURN VALUES
|
||||
This function has no return value.
|
||||
.Sh ERRORS
|
||||
The object pointed to by
|
||||
.Fa epoch
|
||||
must have been previously initiated via
|
||||
.Fn ck_epoch_init 3 .
|
||||
The object pointed to by
|
||||
.Fa record
|
||||
must have been previously registered via
|
||||
.Fn ck_epoch_register 3 .
|
||||
.Sh SEE ALSO
|
||||
.Xr ck_epoch_init 3 ,
|
||||
.Xr ck_epoch_register 3 ,
|
||||
.Xr ck_epoch_unregister 3 ,
|
||||
.Xr ck_epoch_recycle 3 ,
|
||||
.Xr ck_epoch_poll 3 ,
|
||||
.Xr ck_epoch_synchronize 3 ,
|
||||
.Xr ck_epoch_barrier 3 ,
|
||||
.Xr ck_epoch_call 3 ,
|
||||
.Xr ck_epoch_begin 3
|
||||
.Pp
|
||||
Additional information available at http://concurrencykit.org/
|
||||
@ -0,0 +1,68 @@
|
||||
.\"
|
||||
.\" Copyright 2012 Samy Al Bahra.
|
||||
.\" All rights reserved.
|
||||
.\"
|
||||
.\" 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, this list of conditions and the following disclaimer.
|
||||
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||||
.\" notice, 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 REGENTS AND CONTRIBUTORS ``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 REGENTS OR CONTRIBUTORS 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.
|
||||
.\"
|
||||
.\"
|
||||
.Dd September 2, 2012
|
||||
.Dt CK_EPOCH_INIT 3
|
||||
.Sh NAME
|
||||
.Nm ck_epoch_init
|
||||
.Nd initialize epoch reclamation object
|
||||
.Sh LIBRARY
|
||||
Concurrency Kit (libck, \-lck)
|
||||
.Sh SYNOPSIS
|
||||
.In ck_epoch.h
|
||||
.Ft void
|
||||
.Fn ck_epoch_init "ck_epoch_t *epoch"
|
||||
.Sh DESCRIPTION
|
||||
The
|
||||
.Fn ck_epoch_init
|
||||
function initializes the epoch object pointed to by the
|
||||
.Fa epoch
|
||||
pointer.
|
||||
.Sh RETURN VALUES
|
||||
This function has no return value.
|
||||
.Sh ERRORS
|
||||
.Bl -tag -width Er
|
||||
.Pp
|
||||
The behavior of
|
||||
.Fn ck_epoch_init
|
||||
is undefined if
|
||||
.Fa epoch
|
||||
is not a pointer to a
|
||||
.Tn ck_epoch_t
|
||||
object.
|
||||
.El
|
||||
.Sh SEE ALSO
|
||||
.Xr ck_epoch_register 3 ,
|
||||
.Xr ck_epoch_unregister 3 ,
|
||||
.Xr ck_epoch_recycle 3 ,
|
||||
.Xr ck_epoch_poll 3 ,
|
||||
.Xr ck_epoch_synchronize 3 ,
|
||||
.Xr ck_epoch_barrier 3 ,
|
||||
.Xr ck_epoch_call 3 ,
|
||||
.Xr ck_epoch_begin 3 ,
|
||||
.Xr ck_epoch_end 3
|
||||
.Pp
|
||||
Additional information available at http://concurrencykit.org/
|
||||
@ -0,0 +1,72 @@
|
||||
.\"
|
||||
.\" Copyright 2012 Samy Al Bahra.
|
||||
.\" All rights reserved.
|
||||
.\"
|
||||
.\" 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, this list of conditions and the following disclaimer.
|
||||
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||||
.\" notice, 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 REGENTS AND CONTRIBUTORS ``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 REGENTS OR CONTRIBUTORS 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.
|
||||
.\"
|
||||
.\"
|
||||
.Dd September 2, 2012
|
||||
.Dt CK_EPOCH_POLL 3
|
||||
.Sh NAME
|
||||
.Nm ck_epoch_poll
|
||||
.Nd non-blocking poll of epoch object for dispatch cycles
|
||||
.Sh LIBRARY
|
||||
Concurrency Kit (libck, \-lck)
|
||||
.Sh SYNOPSIS
|
||||
.In ck_epoch.h
|
||||
.Ft bool
|
||||
.Fn ck_epoch_poll "ck_epoch_t *epoch" "ck_epoch_record_t *record"
|
||||
.Sh DESCRIPTION
|
||||
The
|
||||
.Fn ck_epoch_poll 3
|
||||
function will attempt to dispatch any functions associated with the
|
||||
object pointed to by
|
||||
.Fa epoch
|
||||
via
|
||||
.Fn ck_epoch_call 3
|
||||
if deemed safe. This function is meant to be used in cases epoch
|
||||
reclamation cost must be amortized over time in a manner that does
|
||||
not affect caller progress.
|
||||
.Sh RETURN VALUES
|
||||
This function will return true if at least one function was dispatched.
|
||||
This function will return false if it has determined not all threads have
|
||||
observed the latest generation of epoch-protected objects. Neither value
|
||||
indicates an error.
|
||||
.Sh ERRORS
|
||||
Behavior is undefined if the object pointed to by
|
||||
.Fa epoch
|
||||
is not a valid epoch object. The object pointed to by
|
||||
.Fa record
|
||||
must have been previously registered via
|
||||
.Fn ck_epoch_register 3 .
|
||||
.Sh SEE ALSO
|
||||
.Xr ck_epoch_init 3 ,
|
||||
.Xr ck_epoch_register 3 ,
|
||||
.Xr ck_epoch_unregister 3 ,
|
||||
.Xr ck_epoch_recycle 3 ,
|
||||
.Xr ck_epoch_synchronize 3 ,
|
||||
.Xr ck_epoch_barrier 3 ,
|
||||
.Xr ck_epoch_call 3 ,
|
||||
.Xr ck_epoch_begin 3 ,
|
||||
.Xr ck_epoch_end 3
|
||||
.Pp
|
||||
Additional information available at http://concurrencykit.org/
|
||||
@ -0,0 +1,101 @@
|
||||
.\"
|
||||
.\" Copyright 2012 Samy Al Bahra.
|
||||
.\" All rights reserved.
|
||||
.\"
|
||||
.\" 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, this list of conditions and the following disclaimer.
|
||||
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||||
.\" notice, 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 REGENTS AND CONTRIBUTORS ``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 REGENTS OR CONTRIBUTORS 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.
|
||||
.\"
|
||||
.\"
|
||||
.Dd September 2, 2012
|
||||
.Dt CK_EPOCH_RECYCLE 3
|
||||
.Sh NAME
|
||||
.Nm ck_epoch_recycle
|
||||
.Nd return an epoch record that may be used by caller
|
||||
.Sh LIBRARY
|
||||
Concurrency Kit (libck, \-lck)
|
||||
.Sh SYNOPSIS
|
||||
.In ck_epoch.h
|
||||
.Ft ck_epoch_record_t *
|
||||
.Fn ck_epoch_recycle "ck_epoch_t *epoch"
|
||||
.Sh DESCRIPTION
|
||||
The
|
||||
.Fn ck_epoch_recycle 3
|
||||
function attempts to return an unused epoch record object for use by
|
||||
the caller. These epoch records were associated with previous calls
|
||||
to the
|
||||
.Fn ck_epoch_unregister 3
|
||||
function.
|
||||
.Sh EXAMPLE
|
||||
.Bd -literal -offset indent
|
||||
#include <ck_epoch.h>
|
||||
#include <stdlib.h>
|
||||
|
||||
/*
|
||||
* epoch was previously initialized with ck_epoch_init.
|
||||
*/
|
||||
ck_epoch_t *epoch;
|
||||
|
||||
void
|
||||
function(void)
|
||||
{
|
||||
ck_epoch_record_t *record;
|
||||
|
||||
record = ck_epoch_recycle(&epoch);
|
||||
if (record == NULL) {
|
||||
record = malloc(sizeof *record);
|
||||
if (record == NULL)
|
||||
return;
|
||||
|
||||
ck_epoch_register(&epoch, record);
|
||||
}
|
||||
|
||||
/*
|
||||
* After we are done, we will unregister the record so it
|
||||
* can be used by other new participants in the epoch system
|
||||
* provided by the object pointed to by "epoch".
|
||||
*/
|
||||
ck_epoch_unregister(&epoch, record);
|
||||
return;
|
||||
}
|
||||
.Ed
|
||||
.Sh RETURN VALUES
|
||||
This function returns a pointer to a
|
||||
.Dv ck_epoch_record_t
|
||||
object. If no unused record was found to be associated with the
|
||||
object pointed to by
|
||||
.Fa epoch ,
|
||||
then the function will return NULL.
|
||||
.Sh ERRORS
|
||||
Behavior is undefined if the object pointed to by
|
||||
.Fa epoch
|
||||
is not a valid epoch object.
|
||||
.Sh SEE ALSO
|
||||
.Xr ck_epoch_init 3 ,
|
||||
.Xr ck_epoch_register 3 ,
|
||||
.Xr ck_epoch_unregister 3 ,
|
||||
.Xr ck_epoch_poll 3 ,
|
||||
.Xr ck_epoch_synchronize 3 ,
|
||||
.Xr ck_epoch_barrier 3 ,
|
||||
.Xr ck_epoch_call 3 ,
|
||||
.Xr ck_epoch_begin 3 ,
|
||||
.Xr ck_epoch_end 3
|
||||
.Pp
|
||||
Additional information available at http://concurrencykit.org/
|
||||
@ -0,0 +1,66 @@
|
||||
.\"
|
||||
.\" Copyright 2012 Samy Al Bahra.
|
||||
.\" All rights reserved.
|
||||
.\"
|
||||
.\" 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, this list of conditions and the following disclaimer.
|
||||
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||||
.\" notice, 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 REGENTS AND CONTRIBUTORS ``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 REGENTS OR CONTRIBUTORS 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.
|
||||
.\"
|
||||
.\"
|
||||
.Dd September 2, 2012
|
||||
.Dt CK_EPOCH_REGISTER 3
|
||||
.Sh NAME
|
||||
.Nm ck_epoch_register
|
||||
.Nd register a thread for epoch reclamation
|
||||
.Sh LIBRARY
|
||||
Concurrency Kit (libck, \-lck)
|
||||
.Sh SYNOPSIS
|
||||
.In ck_epoch.h
|
||||
.Ft void
|
||||
.Fn ck_epoch_register "ck_epoch_t *epoch" "ck_epoch_record_t *record"
|
||||
.Sh DESCRIPTION
|
||||
The
|
||||
.Fn ck_epoch_register 3
|
||||
function associates a record object specified by the
|
||||
.Fa record
|
||||
pointer with the epoch object pointed to by
|
||||
.Fa epoch .
|
||||
Any thread or processor that will require safe memory reclamation
|
||||
guarantees must register a unique record object. After registration, the
|
||||
object pointed to by the
|
||||
.Fa record
|
||||
argument will have lifetime managed by the underlying epoch sub-system.
|
||||
The record object must not be destroyed after it is associated with a
|
||||
.Fn ck_epoch_register 3
|
||||
call.
|
||||
.Sh RETURN VALUES
|
||||
This function has no return value.
|
||||
.Sh SEE ALSO
|
||||
.Xr ck_epoch_init 3 ,
|
||||
.Xr ck_epoch_unregister 3 ,
|
||||
.Xr ck_epoch_recycle 3 ,
|
||||
.Xr ck_epoch_poll 3 ,
|
||||
.Xr ck_epoch_synchronize 3 ,
|
||||
.Xr ck_epoch_barrier 3 ,
|
||||
.Xr ck_epoch_call 3 ,
|
||||
.Xr ck_epoch_begin 3 ,
|
||||
.Xr ck_epoch_end 3
|
||||
.Pp
|
||||
Additional information available at http://concurrencykit.org/
|
||||
@ -0,0 +1,122 @@
|
||||
.\"
|
||||
.\" Copyright 2012 Samy Al Bahra.
|
||||
.\" All rights reserved.
|
||||
.\"
|
||||
.\" 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, this list of conditions and the following disclaimer.
|
||||
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||||
.\" notice, 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 REGENTS AND CONTRIBUTORS ``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 REGENTS OR CONTRIBUTORS 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.
|
||||
.\"
|
||||
.\"
|
||||
.Dd September 2, 2012
|
||||
.Dt CK_EPOCH_SYNCHRONIZE 3
|
||||
.Sh NAME
|
||||
.Nm ck_epoch_synchronize
|
||||
.Nd block until a grace period has been detected
|
||||
.Sh LIBRARY
|
||||
Concurrency Kit (libck, \-lck)
|
||||
.Sh SYNOPSIS
|
||||
.In ck_epoch.h
|
||||
.Ft void
|
||||
.Fn ck_epoch_synchronize "ck_epoch_t *epoch" "ck_epoch_record_t *record"
|
||||
.Sh DESCRIPTION
|
||||
The
|
||||
.Fn ck_epoch_synchronize 3
|
||||
function will block the caller until a grace period has been
|
||||
detected, according to the semantics of epoch reclamation.
|
||||
Any objects requiring safe memory reclamation which are logically
|
||||
deleted are safe for physical deletion following a call to
|
||||
.Fn ck_epoch_synchronize 3 . This function may also dispatch callbacks
|
||||
associated with
|
||||
.Fa epoch
|
||||
that were previously scheduled via
|
||||
.Fn ck_epoch_call 3 .
|
||||
If you require that all callbacks be dispatched, then it is suggested
|
||||
that you use
|
||||
.Fn ck_epoch_barrier 3
|
||||
instead.
|
||||
.Sh EXAMPLE
|
||||
.Bd -literal -offset indent
|
||||
|
||||
#include <ck_epoch.h>
|
||||
#include <ck_stack.h>
|
||||
#include <stdlib.h>
|
||||
|
||||
/*
|
||||
* epoch was previously initialized with ck_epoch_init.
|
||||
* stack was previously initialized with ck_stack_init.
|
||||
*/
|
||||
ck_epoch_t *epoch;
|
||||
ck_stack_t *stack;
|
||||
|
||||
void
|
||||
function(void)
|
||||
{
|
||||
ck_epoch_record_t *record;
|
||||
ck_stack_entry_t *s;
|
||||
|
||||
record = malloc(sizeof *record);
|
||||
ck_epoch_register(&epoch, record);
|
||||
|
||||
/*
|
||||
* We are using an epoch section here to guarantee no
|
||||
* nodes in the stack are deleted while we are dereferencing
|
||||
* them. This is needed here because there are multiple writers.
|
||||
* If there was only one thread popping from the this stack,
|
||||
* then there is no need to ck_epoch_begin/ck_epoch_end.
|
||||
*/
|
||||
ck_epoch_begin(epoch, record);
|
||||
|
||||
/* Logically delete an object. */
|
||||
s = ck_stack_pop_upmc(stack);
|
||||
|
||||
ck_epoch_end(epoch, record);
|
||||
|
||||
/*
|
||||
* Wait until no threads could possibly have a reference to the
|
||||
* object we just popped (assume all threads are simply executing
|
||||
* ck_stack_pop_upmc).
|
||||
*/
|
||||
ck_epoch_synchronize(epoch, record);
|
||||
|
||||
/* It is now safe to physically delete the object. */
|
||||
free(s);
|
||||
return;
|
||||
}
|
||||
.Sh RETURN VALUES
|
||||
This function has no return value.
|
||||
.Sh ERRORS
|
||||
Behavior is undefined if the object pointed to by
|
||||
.Fa epoch
|
||||
is not a valid epoch object. The object pointed to by
|
||||
.Fa record
|
||||
must have been previously registered via
|
||||
.Fn ck_epoch_register 3 .
|
||||
.Sh SEE ALSO
|
||||
.Xr ck_epoch_init 3 ,
|
||||
.Xr ck_epoch_register 3 ,
|
||||
.Xr ck_epoch_unregister 3 ,
|
||||
.Xr ck_epoch_recycle 3 ,
|
||||
.Xr ck_epoch_poll 3 ,
|
||||
.Xr ck_epoch_barrier 3 ,
|
||||
.Xr ck_epoch_call 3 ,
|
||||
.Xr ck_epoch_begin 3 ,
|
||||
.Xr ck_epoch_end 3
|
||||
.Pp
|
||||
Additional information available at http://concurrencykit.org/
|
||||
@ -0,0 +1,72 @@
|
||||
.\"
|
||||
.\" Copyright 2012 Samy Al Bahra.
|
||||
.\" All rights reserved.
|
||||
.\"
|
||||
.\" 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, this list of conditions and the following disclaimer.
|
||||
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||||
.\" notice, 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 REGENTS AND CONTRIBUTORS ``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 REGENTS OR CONTRIBUTORS 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.
|
||||
.\"
|
||||
.\"
|
||||
.Dd September 2, 2012
|
||||
.Dt CK_EPOCH_UNREGISTER 3
|
||||
.Sh NAME
|
||||
.Nm ck_epoch_unregister
|
||||
.Nd unregister a thread for epoch reclamation
|
||||
.Sh LIBRARY
|
||||
Concurrency Kit (libck, \-lck)
|
||||
.Sh SYNOPSIS
|
||||
.In ck_epoch.h
|
||||
.Ft void
|
||||
.Fn ck_epoch_unregister "ck_epoch_t *epoch" "ck_epoch_record_t *record"
|
||||
.Sh DESCRIPTION
|
||||
The
|
||||
.Fn ck_epoch_unregister 3
|
||||
function allows for the record pointed by the
|
||||
.Fa record
|
||||
pointer to be used as a return value by the
|
||||
.Fn ck_epoch_recycle 3
|
||||
function. This record can now be used by another thread
|
||||
of execution. Behavior is undefined if the object pointed by
|
||||
.Fa record
|
||||
is modified in any way, even after a call is made to the
|
||||
.Fn ck_epoch_unregister 3
|
||||
function.
|
||||
.Sh RETURN VALUES
|
||||
This function has no return value.
|
||||
.Sh ERRORS
|
||||
Behavior is undefined if the object pointed to by
|
||||
.Fa record
|
||||
was not previously associated with the object pointed to by
|
||||
.Fa epoch
|
||||
through a previous call to the
|
||||
.Fn ck_epoch_register 3
|
||||
function.
|
||||
.Sh SEE ALSO
|
||||
.Xr ck_epoch_init 3 ,
|
||||
.Xr ck_epoch_register 3 ,
|
||||
.Xr ck_epoch_recycle 3 ,
|
||||
.Xr ck_epoch_poll 3 ,
|
||||
.Xr ck_epoch_synchronize 3 ,
|
||||
.Xr ck_epoch_barrier 3 ,
|
||||
.Xr ck_epoch_call 3 ,
|
||||
.Xr ck_epoch_begin 3 ,
|
||||
.Xr ck_epoch_end 3
|
||||
.Pp
|
||||
Additional information available at http://concurrencykit.org/
|
||||
Loading…
Reference in new issue