This is an automated email from the git hooks/post-receive script. It was generated because a ref change was pushed to the repository containing the project "". The branch, master has been updated via 69b7dbc24b33a84912f9f6a2074f0b58c9d91e22 (commit) from eb1d8c852dfdba9b37838d2cf3fa047f6c37b76c (commit) Those revisions listed above that are new to this repository have not appeared on any other notification email; so we list those revisions in full, below. - Log ----------------------------------------------------------------- commit 69b7dbc24b33a84912f9f6a2074f0b58c9d91e22 Author: Dries Kimpe <[email protected]> Date: Thu Dec 12 16:40:11 2013 -0600 Move aesop docs to aesop repo ----------------------------------------------------------------------- Summary of changes: code/doc/Makefile.subdir | 2 - code/doc/aesop-pbranch-cancel.txt | 203 ------------------------------------- code/doc/aesop.txt | 68 ------------ 3 files changed, 0 insertions(+), 273 deletions(-) delete mode 100644 code/doc/aesop-pbranch-cancel.txt delete mode 100644 code/doc/aesop.txt Diff of changes: diff --git a/code/doc/Makefile.subdir b/code/doc/Makefile.subdir index 99535a2..2f3ca80 100644 --- a/code/doc/Makefile.subdir +++ b/code/doc/Makefile.subdir @@ -3,8 +3,6 @@ DIR := doc ASCIIDOCSRC += $(DIR)/test.txt \ $(DIR)/pipelining.txt \ $(DIR)/compiling-triton.txt \ - $(DIR)/aesop.txt \ - $(DIR)/aesop-pbranch-cancel.txt \ $(DIR)/fault-injection.txt include $(top_srcdir)/doc/security/Makefile.subdir diff --git a/code/doc/aesop-pbranch-cancel.txt b/code/doc/aesop-pbranch-cancel.txt deleted file mode 100644 index 712f5f2..0000000 --- a/code/doc/aesop-pbranch-cancel.txt +++ /dev/null @@ -1,203 +0,0 @@ -Aesop: how to cancel pbranches -============================== - -== Existing implementation: Oct. 2011 - -for some context, here is an example of how things are done currently -(this is a client doing an RPC): - -[source,c] ----- -pwait -{ - pbranch - { - ret = timer(); - /* if timer triggers, then cancel other branches */ - if(ret == SUCCESS) - aesop_cancel_branches_wait(); - } - pbranch - { - ret = recv(); - /* cancel other branches in any case except when we detect that - * another branch has already started cancelling. - */ - if(ret != CANCELLED) - aesop_cancel_branches_wait(); - } - pbranch - { - ret = send(); - /* cancel branches on send error except when we detect that another - * branch has already started cancelling. - */ - if(ret != CANCELLED && ret != SUCCESS) - aesop_cancel_branches_wait(); - } -} ----- - -The aesop_cancel_branches_wait() works by trying to cancel pbranches in -a loop (with a timer) until the pbranch count hits 1. It has to have a -loop because "signaling" the other pbranches is lossy; there is no -way to guarantee that a pbranch cancel will be honored. It might hit -a pbranch that isn't currently in a blocking call. - -Problems with the current implementation: - -* if two pbranches call cancel simultaneously, it will deadlock -* there are some race conditions re: if a pbranch will detect if it has been - cancelled or not -* the cancel implementation is kludgey and more expensive than it needs to - be because of the timer loop -* semantics are unclear, especially at the aesop resource level -* if the send happens to complete (successfully) after the recv completes, - due to network transport ordering issues, then the - aesop_cancel_branches_wait() call after the recv might be triggered too - early - -== New semantics - -=== Semantics of the aesop-level cancel: -* totally asynchronous (no longer blocks until pbranches exit) -* cancel signal to pbranch is guaranteed to be delivered exactly once -** will affect current resource operation (if present) or the next one to - be posted -** cancel status is cleared for a pbranch once it has impacted one blocking - resource call (so pbranch can issue blocking cleanup functions safely if - it needs to) -* cancel will return true if it succeeded in delivering the cancel request, - false if it detects that another pbranch *at the same scope or higher* - already issued a cancel -** it is Ok if a child pbranch already is already cancelled in its own - scope; just skip that one and return success anyway - -* caller can ignore cancel return code if it doesn't care (most codes will - not) -* illegal to call cancel from a lonely pbranch - -=== Semantics of the resource-level cancel function: -* totally asynchronous -* returns true if it delivered the cancel signal to the operation in - question (and the operation is guaranteed to return ECANCEL or - whatever is appropriate for the resource) -* returns false if it failed to cancel the operation in question -* cancel function can no longer issue op callback directly (this complicates - some possible deadlock scenarios) - -=== Aesop internal implementation details: -* serialize calls to cancel (so that only one pbranch will "win") -* set flag at the pwait level to indicate that the branches have been - cancelled (or return failure if flag already set) -* for each pbranch: -** atomically check for resource op id (and make sure no posts happen - concurrently) -*** if op id present, try resource cancel -**** if success, done -**** if fail, set flag in ctrl structure to say pbranch should cancel -*** if op id not present, set flag in ctrl structure to say pbranch should - cancel -** proceed recursively, setting flag in child pbranches in the same manner - -=== Semantics of the resource-level post functions: -* will have hook to check (and clear) parent ctrl structure cancel flag -* if detect that pbranch has cancelled, the post should immediately fail - with appropriate return code for resource - -=== Misc: -* provide helper functions is_cancelled() and clear_cancelled() so a pbranch - can check and clear it's cancelled status manually if it wants to -* One possible implementation idea is to treat child pwait blocks as - resources, so that they generate op ids and have a cancel function just - like a resource call. Might make the aesop code a little cleaner in - exchange for pushing some complexity elsewhere. Need to look at code to - see if this is worth doing or not. -* A possible extension to this document, would be to name each pbranch and - add the ability to cancel specific pbranches by name. Probably not that - hard to implement, but we don't have a clear use case yet. - -Example using new semantics: - -[source,c] ----- - -while(retry) -{ - /* the send and recv are grouped into a single function - * (do_communication) to make it clearer that we want both to complete - * before cancelling the timer. - * - * The aesop_cancel_branches() call is safe against race conditions, so - * neither pbranch has to check if it has been cancelled before - * initiating an aesop_cancel_branches() of its own. - */ - pwait - { - pbranch - { - ret = timer(); - aesop_cancel_branches(); - } - - pbranch - { - comm_ret = do_communication() - aesop_cancel_branches(); - } - } -} - - -do_communication() -{ - pwait - { - pbranch - { - recv_ret = recv(); - } - pbranch - { - send_ret = send(); - if(ret != SUCCESS) - aesop_cancel_branches(); - } - } - - return(whatever); -} - ----- - -Example resource cancel semantics: - -[source,c] ----- - -triton_ret_t resource_post(void) -{ - /* don't start op if we have a pending, undelivered cancel signal */ - if(test_and_clear_cancelled_state()) - return(ECANCELLED); - - /* do whatever .... */ -} - -triton_ret_t resource_cancel(op_id) -{ - /* lock to protect against post/callback/cancel races */ - - if(queued) - /* move to cancelled queue, return success */ - - if(callback already in progress) - /* return failure */ - - if(cant find operation) - /* return failure */ - -} - ----- - diff --git a/code/doc/aesop.txt b/code/doc/aesop.txt deleted file mode 100644 index 3158c82..0000000 --- a/code/doc/aesop.txt +++ /dev/null @@ -1,68 +0,0 @@ -Aesop -===== - -[WARNING] -This document is out of date, at least as of November 2012. This should be -moved to the aesop repository and updated, especially the list of resources. - -== Source files - -Aesop source and header files are named *.ae and *.hae, respectively. They -are used exactly like c source and header files, except that they support -additional constructs, such as the __blocking qualifier for functions and -the pwait and pbranch constructs. - -In addition, Aesop remote code (ie, RPC functions) can be found in .aer and -.haer functions. These source files support an additional __remote -qualifier for functions to be invoked via RPC. - -== Compilers - -The configure process produces two compilers in the maint/ directory. aecc -is a compiler for .ae files, and aercc is a compiler for .aer files. Both -are shell scripts that combine preprocessing, source translation, and -compilation into one step. - -== Resources - -Resources are the lowest level aesop components that present Aesop -compatible intefaces for managing concurrency. The current list of -resources includes: - -* file resource -** code/src/versioned-osd/prototype/file-resource -** provides a mapping of open, close, read, write etc. functions. It uses - a thread pool by default to implement nonblocking semantics. - -* Berkeley DB resource -** code/src/versioned-osd/prototype/bdb-resource -** provides a mapping of common Berkeley DB functions. It uses a thread - pool by default to implement nonblocking semantics. - -* socket resource -** code/src/common/resources/aesocket/ -** waits for a file descriptor to be ready for read or write operations. - It does not implement actual read or write calls; it is assumed that the - caller will use this resource in conjunction with nonblocking reads and - writes. It uses libev, which in turn uses epoll() on Linux. - -* timer resource -** code/src/common/resources/timer/ -** implements timers with millisecond resolution. The underlying - implementation uses libev. - -* scheduling resource -** code/src/common/resource/scheduling/ -** Implements various synchronization primitives, for example Aesop - equivalents for condition variables. - -* branch threader resource -** code/src/common/resource/branch-threader/ -** Proof of concept that allows the developer to manually allocate a thread - for particular aesop code blocks. - -== Test programs - -A variety of tests and/or examples for Aesop functionality can be found in -the code/src/aesop/parser/tests/blocking directory. These tests use a -dummy resource to demonstrate various language features. hooks/post-receive --