From 357324dd3ee3790a4e92d9ab9fdc20fc30bd497d Mon Sep 17 00:00:00 2001 From: Samy Al Bahra Date: Mon, 26 Oct 2015 17:58:34 -0400 Subject: [PATCH] doc/ck_epoch: Update documentation for epoch sections. --- doc/ck_epoch_barrier | 8 ++++---- doc/ck_epoch_begin | 6 ++++-- doc/ck_epoch_call | 8 ++++---- doc/ck_epoch_end | 9 ++++----- doc/ck_epoch_synchronize | 14 +++++--------- doc/ck_epoch_unregister | 10 +--------- 6 files changed, 22 insertions(+), 33 deletions(-) diff --git a/doc/ck_epoch_barrier b/doc/ck_epoch_barrier index 80cc70e..a586145 100644 --- a/doc/ck_epoch_barrier +++ b/doc/ck_epoch_barrier @@ -34,7 +34,7 @@ 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" +.Fn ck_epoch_barrier "ck_epoch_record_t *record" .Sh DESCRIPTION The .Fn ck_epoch_barrier 3 @@ -77,19 +77,19 @@ function(void) * 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); + ck_epoch_begin(record); /* Logically delete an object. */ s = ck_stack_pop_upmc(stack); - ck_epoch_end(epoch, record); + ck_epoch_end(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); + ck_epoch_barrier(record); /* It is now safe to physically delete the object. */ free(s); diff --git a/doc/ck_epoch_begin b/doc/ck_epoch_begin index 6a71860..a44ecf8 100644 --- a/doc/ck_epoch_begin +++ b/doc/ck_epoch_begin @@ -34,7 +34,7 @@ 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" +.Fn ck_epoch_begin "ck_epoch_record_t *record" "ck_epoch_section_t *section" .Sh DESCRIPTION The .Fn ck_epoch_begin 3 @@ -44,7 +44,9 @@ An epoch-protected code section is delimited by a call to the 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. +that is at the top of the call stack. If a section is passed, then +recursion on a record will cause the epoch to be refreshed on entry +of every protected section. .Sh RETURN VALUES This function has no return value. .Sh ERRORS diff --git a/doc/ck_epoch_call b/doc/ck_epoch_call index 288814e..7390642 100644 --- a/doc/ck_epoch_call +++ b/doc/ck_epoch_call @@ -37,7 +37,7 @@ typedef struct ck_epoch_entry ck_epoch_entry_t; .br typedef void ck_epoch_cb_t(ck_epoch_entry_t *); .Ft void -.Fn ck_epoch_call "ck_epoch_t *epoch" "ck_epoch_record_t *record" "ck_epoch_entry_t *entry" "ck_epoch_cb_t *function" +.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 @@ -102,15 +102,15 @@ function(void) * writers. It is also an option to use other forms of blocking * write-side synchronization such as mutexes. */ - ck_epoch_begin(epoch, record); + ck_epoch_begin(record); n = ck_pr_fas_ptr(&global, n); - ck_epoch_end(epoch, record); + ck_epoch_end(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); + ck_epoch_poll(record); return; } .Ed diff --git a/doc/ck_epoch_end b/doc/ck_epoch_end index eea2dad..a36afbd 100644 --- a/doc/ck_epoch_end +++ b/doc/ck_epoch_end @@ -34,19 +34,18 @@ 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" +.Fn ck_epoch_end "ck_epoch_record_t *record" "ck_epoch_section_t *section" .Sh DESCRIPTION The .Fn ck_epoch_end 3 function will mark the end of an epoch-protected code section. +.Fa section +must point to a section object initialized previously with +.Fn ck_epoch_begin 3 . .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 . diff --git a/doc/ck_epoch_synchronize b/doc/ck_epoch_synchronize index 33df67c..6c9a698 100644 --- a/doc/ck_epoch_synchronize +++ b/doc/ck_epoch_synchronize @@ -34,7 +34,7 @@ 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" +.Fn ck_epoch_synchronize "ck_epoch_record_t *record" .Sh DESCRIPTION The .Fn ck_epoch_synchronize 3 @@ -80,19 +80,19 @@ function(void) * 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); + ck_epoch_begin(record); /* Logically delete an object. */ s = ck_stack_pop_upmc(stack); - ck_epoch_end(epoch, record); + ck_epoch_end(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); + ck_epoch_synchronize(record); /* It is now safe to physically delete the object. */ free(s); @@ -102,11 +102,7 @@ function(void) .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 +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 , diff --git a/doc/ck_epoch_unregister b/doc/ck_epoch_unregister index 9f297ee..3be537f 100644 --- a/doc/ck_epoch_unregister +++ b/doc/ck_epoch_unregister @@ -34,7 +34,7 @@ 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" +.Fn ck_epoch_unregister "ck_epoch_record_t *record" .Sh DESCRIPTION The .Fn ck_epoch_unregister 3 @@ -50,14 +50,6 @@ is modified in any way, even after a call is made to the 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 ,