February 2012 - Asg - mailman3.cels.anl.gov

Slides for our review next week
by Ward, Lee 25 Feb '12

25 Feb '12

All, Please find, attached, much of the slide deck I intend we use for our review next week. Please check it and give me comments? Please check it for your contribution to make sure that is what you really want to say and that I haven't screwed up? Note that the ANL and ORNL contributions are not yet present. I needed to do this deck before they could really contribute. We will be "tag-teaming" the presentation so they needed some idea of the flow before they could craft their parts. Note, also, there is no pretty template. I am required to use the Sandia template but that just cannot happen in this case, it's solely my presentation, it's all of us here. I suspect Joan, at ORNL, will end up sticking all of this in a template to the customer's liking. For everyone who decided they could go edge-to-edge-to-edge on their contribution, the outside borders will either be covered or your content grouped and ruthlessly shrunk to fit, making it nearly unreadable. You might want to rethink what you really want there and get me an update by COB tomorrow, 2/23. You'll note that this deck is too long, I'll keep working to make it smaller but in the end I may be racing through the slides. I won't have the time to linger long on any slide. A short, powerful, message will rule the day. --Lee

4 5

aesop Repository branch, master, updated. 532859b80da020901b9df4f2a2b6ad918f279a62
by noreply＠mcs.anl.gov 24 Feb '12

24 Feb '12

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 "aesop Repository". The branch, master has been updated via 532859b80da020901b9df4f2a2b6ad918f279a62 (commit) from b1a353910dc7653896225a342edcf76a37bdab22 (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 532859b80da020901b9df4f2a2b6ad918f279a62 Author: Phil Carns <carns(a)mcs.anl.gov> Date: Fri Feb 24 17:33:07 2012 -0500 fill in more text for complexity analysis ----------------------------------------------------------------------- Summary of changes: doc/aesop-performance.txt | 70 +++++++++++++++++++++++++++------------------ 1 files changed, 42 insertions(+), 28 deletions(-) Diff of changes: diff --git a/doc/aesop-performance.txt b/doc/aesop-performance.txt index 850df4a..96e7845 100644 --- a/doc/aesop-performance.txt +++ b/doc/aesop-performance.txt @@ -373,8 +373,6 @@ set of complexity metrics. | event | 28 | 23 | 341 |============================ -// @TODO: Need to update the table with other forms of threading - ////// \begin{table} \small @@ -393,32 +391,46 @@ set of complexity metrics. \end{table} ///// -<<table-complex>> compares the code complexity of each implementation using McCabe -Cyclomatic Complexity (CC) <<McCabe>>, Modified McCabe Cyclomatic Complexity -(Mod. CC), and Source Lines of Code (SLOC). - -//TODO: reference the -//metrics and the tools that we used to collect them (pmccabe and sloccount). - -To simplify the comparison, error handling was excluded for all servers except -for assertions on expected return codes. The protocol definition (ie, -request and acknowledgement structs) as well as helper functions to loop -over send and receive were not counted in any of the implementations, as these -were similar in all four. - -Aesop and thread are very similar in terms of complexity, with the slight -increase in the thread model due to function calls needed to create and join -threads. - -Thread pool and event model are both much more complex than the thread or -aesop model. An additional complexity of the event model which is not -captured by these metrics is the fact that control flow is not preserved -across the processing of a given request. For example, servicing a write -operation requires 5 disconnected event handlers. So although the event -model appears less complex according to CC and mod. CC, qualitatively it is -significantly more challenging to develop. - - +<<table-complex>> compares the code complexity of each server +implementation using McCabe Cyclomatic Complexity (CC) <<McCabe>>, +Modified McCabe Cyclomatic Complexity (Mod. CC), and Source Lines of Code +(SLOC). The CC and Mod. CC metrics were measured using the pmccabe tool, +version 2.6, created by Paul Bame <<Bame>>, while the SLOC metrics were +measured using the sloccount tool, version 2.26, +created by David A. Wheeler <<Wheeler>>. + +To simplify the comparison, error handling was excluded for all servers +except for assertions on expected return codes. The protocol definition +(ie, request and acknowledgement structs) as well as helper functions to +loop over send and receive were not counted in any of the implementations, +as these were similar in all four. Also note that the Aesop version +does not include the Aesop standard library, which +provides a binding between Aesop and the standard POSIX socket API as part +of its default functionality. The focus +of this comparison is on the core logic defining the server implementation. + +The Aesop and thread-per-client servers are very similar in terms of complexity. The +slight increase in complexity for the thread-per-client server results from +the additional function calls needed to create and join threads. The +nonblocking version of the thread-per-client server (thread-per-client-nb) +uses two additional lines of code to place each socket into non-blocking +mode. The remaining code logic needed to manage the nonblocking socket +calls is implemented in helper functions which are not included in the +analysis. + +The thread-pool and event models are both much more complex than the +thread-per-client or aesop model. In the case of the thread-pool server, +this additional complexity arises from not only the queueing and thread +management logic, but also the event loop which is necessary to detect +incoming requests and dispatch them to the queue. The event server +complexity arises from the necessity of dividing servicing routines into multiple +sub-functions and manually tracking state between those functions. +An additional complexity of the event +model which is not captured by these metrics is the fact that control flow +is not preserved across the processing of a given request. For example, +servicing a write operation requires 5 disconnected event handlers. +Although the event model appears less complex than the thread-pool model according to CC and +Mod. CC, qualitatively it is significantly more challenging to develop. === Performance Evaluation @@ -463,3 +475,5 @@ image::fig/read-null-mem.png["Read-null test server memory usage"] [bibliography] - [[[McCabe]]] McCabe, T.J. A Complexity Measure. In IEEE Transactions on Software Engineering, vol.SE-2, no.4, pp. 308- 320, Dec. 1976. +- [[[Bame]]] Paul Bame. pmccabe. http://parisc-linux.org/~bame/pmccabe/ +- [[[Wheeler]]] David A. Wheeler. sloccount. http://www.dwheeler.com/sloc/ hooks/post-receive -- aesop Repository

1 0

aesop Repository branch, master, updated. b1a353910dc7653896225a342edcf76a37bdab22
by noreply＠mcs.anl.gov 24 Feb '12

24 Feb '12

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 "aesop Repository". The branch, master has been updated via b1a353910dc7653896225a342edcf76a37bdab22 (commit) from ee08819538bcbb4be377f2d30c88c5aeaaa4fdce (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 b1a353910dc7653896225a342edcf76a37bdab22 Author: Dries Kimpe <dkimpe(a)mcs.anl.gov> Date: Thu Feb 23 15:42:08 2012 -0600 Aesop user guide ----------------------------------------------------------------------- Summary of changes: doc/aesop-user-guide.txt | 77 ++--------- doc/aug_external.txt | 271 ++++++++++++++++++++++++++++++++++++++ doc/aug_introduction.txt | 329 ++++++++++++++++++++++++++++++++++++++++++++++ doc/aug_language.txt | 4 + doc/aug_preface.txt | 64 +++++++++ doc/aug_standard.txt | 263 ++++++++++++++++++++++++++++++++++++ doc/module.mk.in | 5 + 7 files changed, 950 insertions(+), 63 deletions(-) create mode 100644 doc/aug_external.txt create mode 100644 doc/aug_introduction.txt create mode 100644 doc/aug_language.txt create mode 100644 doc/aug_preface.txt create mode 100644 doc/aug_standard.txt Diff of changes: diff --git a/doc/aesop-user-guide.txt b/doc/aesop-user-guide.txt index 550ff16..330a64b 100644 --- a/doc/aesop-user-guide.txt +++ b/doc/aesop-user-guide.txt @@ -1,72 +1,23 @@ +Aesop User Guide +================= +author +v0.1, 2012-01 +:doctype: book -Aesop -===== +// ------------------------------------------------------------------------- +// ------------------------------------------------------------------------- +// ------------------------------------------------------------------------- +// ------------------------------------------------------------------------- -== Source files +include::aug_preface.txt[] -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. +include::aug_introduction.txt[] -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. +include::aug_language.txt[] -== Compilers +include::aug_standard.txt[] -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. +include::aug_external.txt[] -[source,c] ----- -sdafa -sdfa -sdfasdf ----- -== 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. diff --git a/doc/aug_external.txt b/doc/aug_external.txt new file mode 100644 index 0000000..a5ac4b6 --- /dev/null +++ b/doc/aug_external.txt @@ -0,0 +1,271 @@ +Interfacing with external C libraries +===================================== + +Non-blocking functions +---------------------- + +Non-blocking functions can be called directly. + +If the library provides an asynchronous interface, even though +Currently, there are two ways to do this. + +The first one is to use the _ResourceBuilder_ module (described below). +The second one is to write an aesop resource for the library. + +ResourceBuilder +^^^^^^^^^^^^^^^ + + + + +Blocking functions +------------------- + + + + + +[[ref-thread]] +Using the `thread` module +^^^^^^^^^^^^^^^^^^^^^^^^^ + +[NOTE] +===== +The BranchThreader module relies on the internals of the current +source-to-source translator. +===== + + +///////////// + +\subsection{Resources and Events} + +We treat asynchronous events as being produced by \emph{resources}. +Resources are logical components of the system (on a single node) that perform +operations for a period of time. Examples include network cards, storage +devices, scheduling, timing + +\begin{figure} + %\vskip -0.25in + \centering + \includegraphics[keepaspectratio,width=0.45\textwidth]{model.pdf} + \caption{Model of devices, server state, and server code. + \label{fig:model} + } +\end{figure} + +% I don't think limited in capacity is a resource requisite. +% From a usage point of view: maybe; From aesop language point of view: a +% resource is a undivisable blocking function. (i.e. a blocking function which +% itself doesn't call any aesop blocking functions) +% +Mention properties of resources: +limited in capacity, capability +often require or benefit from scheduling +This should invoke the notion of queueing, delaying, waiting, etc. +of operations that are given to resources. + +In practice, interfaces to a resource usually consist +of a basic set of asynchronous or non-blocking function calls provided as +a userspace library. + +\subsection{Serial Control Flow} + +\subsection{Misc. notes} + +\color{red} +Somewhere (not sure where in the paper) we should address how aesop uses +multiple cores. Right now, normal c code may or may not be executed in a +thread depending one what path is the lowest latency following a given +resource event. However, you can add advisory hints to tell aesop to run +code branches in a thread? See discussion on mailing list and go with +whatever we end up settling on there. +\color{black} + + +Aesop has no such restriction on which +thread executes non-async code. Continuation of aesop functions can +be driven by a single thread in the aesop poll engine, by threaded +callbacks from resources, or (hypothetically, we haven't implemented +this) by a thread pool in the aesop poll engine. \color{black} + +///////// + + + +Creating a new resource +----------------------- + +In some cases, more advanced contro + +---- +struct ae_resource +{ + const char *resource_name; + int (*test)(ae_op_id_t id, int ms_timeout); + int (*poll_context)(ae_context_t context); + int (*cancel)(ae_context_t ctx, ae_op_id_t id); + int (*register_context)(ae_context_t context); + int (*unregister_context)(ae_context_t context); + struct ae_resource_config* config_array; /* terminated by entry with NULL name */ +}; +---- + + + +////////// + +\subsection{Resources and Events} + +We treat asynchronous events as being produced by \emph{resources}. +Resources are logical components of the system (on a single node) that perform +operations for a period of time. Examples include network cards, storage +devices, scheduling, timing + +\begin{figure} + %\vskip -0.25in + \centering + \includegraphics[keepaspectratio,width=0.45\textwidth]{model.pdf} + \caption{Model of devices, server state, and server code. + \label{fig:model} + } +\end{figure} + +% I don't think limited in capacity is a resource requisite. +% From a usage point of view: maybe; From aesop language point of view: a +% resource is a undivisable blocking function. (i.e. a blocking function which +% itself doesn't call any aesop blocking functions) +% +Mention properties of resources: +limited in capacity, capability +often require or benefit from scheduling +This should invoke the notion of queueing, delaying, waiting, etc. +of operations that are given to resources. + +In practice, interfaces to a resource usually consist +of a basic set of asynchronous or non-blocking function calls provided as +a userspace library. + +\subsection{Serial Control Flow} + +\subsection{Misc. notes} + +\color{red} +Somewhere (not sure where in the paper) we should address how aesop uses +multiple cores. Right now, normal c code may or may not be executed in a +thread depending one what path is the lowest latency following a given +resource event. However, you can add advisory hints to tell aesop to run +code branches in a thread? See discussion on mailing list and go with +whatever we end up settling on there. +\color{black} + + +Aesop has no such restriction on which +thread executes non-async code. Continuation of aesop functions can +be driven by a single thread in the aesop poll engine, by threaded +callbacks from resources, or (hypothetically, we haven't implemented +this) by a thread pool in the aesop poll engine. \color{black} +////////// + + +///// + +What is a resource? +A resource is a very thin shim layer that converts aesop blocking calls into async calls to some system resource or system library (like mpi, file access, ssm, etc.) + +A resource API uses the same types and conventions as the underlying resource; we don't try to hide any of that. It just handles how to post and complete blocking operations. + +Aesop is re-entrant and uses threads. + +A resource can use a number of progress models: + +if the resource has its own threads or progress engine, then it can trigger callbacks that drive the next aesop execution state +if the resource is passive, it can request polling from aesop and aesop will drive it with explicit poll calls +Polling resources can "busy poll" or just indicate specific times when they would like to be polled +Creating a new resource +Look at resources/timer/timer.c as an example. + +The most important file that a resource will use to help define its interface is resource.h, which can be found in the top level directory. + +The ae_resource struct defines the interface to each resource. It includes the following pointers: + +resource_name +test() +poll_context() +cancel() +register_context() +unregister_context() +config_array() +resource_name is the only mandatory field. The others are optional depending on what functionality your resource provides. + +SSM as an example +In ssm, the user calls a function called ssm_wait() which will trigger callbacks. ssm_wait() takes a timeout argument to tell it how long to wait. The callbacks are executed in serial in the context of the wait() call. wait() does not spawn threads. The callback functions can do pretty much anything; they can even post new SSM operations. + +SSM init function returns a handle. A use case for calling init twice and getting two handles would be if you wanted to use two transports simultaneously. + +SSM makes progress on communication autonomously, even if you don't call wait(). So wait() does not drive communication progress, it only lets you find completion events. + +If the ssm_wait() function is sleeping in one thread, while another thread registers a callback and does a put/get, then the wait _will_ pick up the new completion event. You don't have to restart the wait() call. This simplifies the resource greatly. + +Kevin's example of an SSM resource + +General plan: Kevin will provide a basic, possibly poor performing ssm resource, UAB team will own it from there to test performance and tune it, change threading, etc. to match best practice for SSM performance. + +Issues: we have to decide (soon, not necessarily today) where to host resources. Should ssm be part of the aesop repo, or should there be separate repos so that not every aesop user gets ssm, etc. + +Code walkthrough + +There are some minor differences between "in tree" version of aesop within the triton repo, and the "stand alone" version of aesop that we are working with. Kevin's example is in tree, and will need some minor porting to go along with aesop. + +Error codes: functions that aesop actually uses directly (init and finalize are good examples) you must use pre-defined error codes. For functions that are specific to your resource (like put() and get()) you can do absolutely anything that you want. + +There is a call to register the initialization and finalization routines (triton_init_register()). + +The initialization function: register the resource with aesop, specify the ae_resource struct that fills in function pointers for various functionality. Then you create a default context. + +Right now the transport and address are hard coded (using tcp on localhost). + +ae_define_post(... triton_ssm_put ...) +The ae_define_post lets you specify a blocking function and its arguments. It (behind the scenes) tacks on extra arguments that are needed by aesop. + +Blocking functions like this can support immediate completion. SSM does not do this yet, but it is something we can discuss later as an optimization. The idea is to avoid context switch to another thread if you post an operation that can be finished in place. + +The opcache is an aesop thing that lets you allocate a struct to represent an in-flight operation (an "op"). It has a user-definable field that you can use to tack on information specific to your resource. + +The following macro populates the op structure with fields to tell aesop what to do when the operation completes: + +ae_op_fill_with_params() +General comment: this example needs one line comments explaining what's going on, and point out which things are optional. + +General comment: it might be a good idea for ANL to just implement some basic functions and then hand off to UAB to fill in remainder, would be a good exercise for everyone. + +This function can be used to track operations (put them in whatever queues you would like as a resource imlementor): + +ae_ops_enqueue() +The caller of ae_ops_enqueue() is responsible for appropriate locking when modifying or moving op structures around. Until the resource completes an operation (and hands off control to aesop) it is the resource's responsibility to handle them until then. + +The following function handles polling: + +triton_ssm_poll() +Right now the resource busy spins and expects aesop to call the poll function constantly. We know that this is not a final implementation. In the longer term we want this resource to have a thread that drives the wait() function. Once that is in place then the poll function is no longer needed. + +General issue: we need to discuss whether to keep wrappers for things like triton_mutex_lock(). If we do want to keep wrappers, we need to decide whether each component does its own wrappers or we all agree on a centralized implementation/wrapper across the project. + +Future work (not enough time in this session) +Need to address semantics of ssm in relation to anl/triton work, independent of the resource implementation. Let's pick back up on that this afternoon after completing the agenda. + +UAB can also send visitors to ANL easily if we need more interaction later. + +//// + +Resources are the lowest level aesop components that present Aesop +compatible intefaces for managing concurrency. The current list of +resources includes: + +. resourcebuilder +. branchthreader +. timer + + + + diff --git a/doc/aug_introduction.txt b/doc/aug_introduction.txt new file mode 100644 index 0000000..afab064 --- /dev/null +++ b/doc/aug_introduction.txt @@ -0,0 +1,329 @@ + +Introduction +============ + + +Installing Aesop +---------------- + +This section describes how to obtain, build and install the aesop +source-to-source translator. + + +Prerequisites +~~~~~~~~~~~~~ + +[NOTE] +===== +These are the requirements of the aesop source-to-source translator. +Executables compiled from aesop source code do not require any additional +packages, except for those required used by the program itself. For example, +there is no need to have a haskell installed when running an executable +created using the aesop source-to-source translator. +==== + + +Aesop currently requires the following: + +* The Glasgow Haskell compiler, version 7.0 or later + (http://www.haskell.org/ghc/) +* OpenPA (The Open Portable Atomics library, + http://trac.mcs.anl.gov/projects/openpa) +* wget +* A pthreads compatible system. + +* At least 2 GiB of memory + + +Mac OS X +^^^^^^^^^ + +For Mac OS X, the following additional packages are required: + +* coreutils + +Make sure the coreutils installation directory is added to the search path +(+$PATH+). + +A Mac OS haskell package can be downloaded from http://hackage.haskell.org/platform/mac.html. + + +Developer Version +^^^^^^^^^^^^^^^^^^ + +When building aesop from the git source code repository, the following extra +packages are required: + +* A git client. Git can be downloaded from http://git-scm.com/download. +* autoconf (http://www.gnu.org/s/autoconf/) + + +Installation of the aesop dependencies +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Glasgow Haskell Compiler +^^^^^^^^^^^^^^^^^^^^^^^^ + +[TIP] + Many linux distributions, such +as Ubuntu and Debian, contain this package. If your linux distribution has a +pacakge for the Glasgow Haskell Compiler (typically named 'ghc'), we recommend +installing ghc on your system using the distribution's package manager. +If your distribution does not include a package, or you do not want to install +the package system-wide, the compiler can be installed using the instructions +below. + + +Aesop requires the Glasgow Haskell Compiler (ghc). If root +access (required for many package managers) is not available, +or system wide installation of ghc is not desired, +it is possible to install the ghc binaries in a home +directory. + +The binary builds can be found here: +http://www.haskell.org/ghc/download_ghc_7_2_2#binaries + +Additional Haskell Modules +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Aesop requires some additional haskell modules: + +* transformers, version 0.2.2.0 +* mtl, version 2.0.1.0 +* happy, version 1.18.6 +* alex, version 2.3.5 +* regex-base, version 0.93.2 +* regex-posix, version 0.94.4 +* regex-pcre-builtin, version 0.94.2.1.7.7 +* syb, version 0.3 + +To simplify installing these packages, the aesop distribution contains scripts +to download and install these modules. These scripts expect the +wget+ +utility to be in the default search path. The +wget+ utility should be +available as a package on your platform. + +To run these scripts, change to the +aesop/main/hs+ directory and execute +the following commands (as a normal user, no root privileges required): + +------ +./setup-hs-local +./setup-langc +------ + +[[ref-openpa]] +The Open Portable Atomics Library +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +[TIP] +===== +Recent versions of the mpich MPI library include OpenPA. +If mpich is installed, there is no need to install OpenPA. +===== + +The Open Portable Atomic Library can be downloaded from the following +location: http://trac.mcs.anl.gov/projects/openpa. +Configure using the included `configure` script, optionally specifying where +the library needs to be installed (using the `--prefix` option). If installing +in a non-standard location, make sure to use the `--with-openpa` + + +Obtaining the Aesop distribution +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Right now, the only way to obtain the aesop distribution is directly from +our source code repository. For this, +git+ is required (http://git-scm.com) + +In the future, we will release stable aesop source archives through the aesop +website. + +Obtaining Aesop from the source code repository +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +[NOTE] +.The Aesop source code repository +======= +The aesop source code repository contains the latest aesop source code, which +changes on a daily basis. As such, from time to time, the code in the +repository might contain bugs or fail to build. If that is the case, please +let us know by opening a ticket at http://trac.mcs.anl.gov/projects/aesop. +========= + +In order to install Aesop is is necessary to first clone the repository. +The aesop source code repository is public and can be cloned by +anonymous users: + +------ +git clone git://git.mcs.anl.gov/aesop +------ + +[NOTE] +.Read/write access +======================== +We welcome all contributions and patches. + +Frequent contributors can request write access to the aesop repository by +sending a a public key (in OpenSSH format) to Phil Carns +(mailto:[email protected][[email protected]]). + +To clone the repository with support for write access, use the following git +command: + +------ +git clone [email protected]:aesop.git +------ +======================= + +The aesop code is split into multiple submodules. +Once the aesop repository is cloned, these submodules must be initialized. + +----------- +cd aesop +git submodule init +git submodule update +----------- + +[TIP] +In git version 1.6.5 or later, the submodules can be automatically initialized +and updated when cloning the aesop repository by using the +--recursive+ +parameter. + +The source code repository does not include the final configuration and build +scripts. To generate these, please run the following command in the root +directory of the aesop directory: + +---------- +./prepare +---------- + +Configuring Aesop +^^^^^^^^^^^^^^^^^ + +Now there should be a script named +configure+ in the aesop root directory. + +It is possible to compile aesop in the source directory, but we usually +recommend doing an "out of tree build". To do this, create a build +subdirectory inside the aesop directory and then run configure and make from +there: + +---- +mkdir build +cd build +../configure +---- + +If the OpenPA installation is in a non-standard location (see <<ref-openpa>>) +then the `--with-openpa=<path>` option can be used to tell configure where to +find the openpa library. + +[NOTE] +==== +When doing an out of tree build, it is important to be in the desired build +directory when executing the configure script. +==== + +Building Aesop +^^^^^^^^^^^^^^ + +To build aesop, run `make` within the build-aesop directory: + +----- +make -j 4 +----- + +[NOTE] +==== +Specifying +-j 4+ is optional, but the aesop build system does support +parallel builds, reducing the build time on most systems. +==== + +Building and running the Aesop test suite +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The aesop distribution includes a large number of test programs, +designed to exercise the language features and the translator. + +These test programs can be built using the following command (in the build +directory). + +---- +make test +---- + +To run the tests, use the '++check++' target instead. + +---- +make check +---- + +[NOTE] +===== +At this time, some of the tests are not completing (successfully). +This will be fixed soon. +===== + + +Installing Aesop +^^^^^^^^^^^^^^^^ + +To install aesop, use the following command: + +---- +make install +---- + +Unless specified otherwise (using the +--prefix+ option at configure time), +aesop will be installed into the +/usr/local+ directory. + +The configure process produces two scripts in the maint/ directory. aecc +is a translator for .ae files, and aercc is a translator for .aer files. Both +are shell scripts that combine preprocessing, source translation, and +compilation into one step. These wrappers will be during the +installation process. + + +Using the Aesop Source-To-Source Translator +------------------------------------------- + + + +File Dependencies +~~~~~~~~~~~~~~~~~~ + +[graphviz] +.Translation Dependencies +--------------- +digraph G +{ + subgraph P + { + rank = "same"; + ae [label="example.ae"]; + hae [label="example.hae"]; + }; + subgraph P2 + { + rank="same"; + ae_s [label="example.ae.s"]; + h [label="example.h"]; + } + o [label="example.o"]; + ae_s -> o [label="C compiler"]; + ae -> ae_s [label="Aesop translator"]; + hae -> h [label="Aesop translator"]; + ae -> hae [label="includes",style="dashed"]; + ae_s -> h [label="includes",style="dashed"]; +} +--------------- + + +[TIP] +===== +To see the intermediate C code generated by aesop (instead +of going directly from .ae files to .o files), configure aesop with the +`--enable-aesop-debug` configure option. Doing so will cause +additional ae.i and ae.s files to be created during the compilation of aesop code. +These files contain the C translation of the aesop source code. +===== + + + diff --git a/doc/aug_language.txt b/doc/aug_language.txt new file mode 100644 index 0000000..3084d2a --- /dev/null +++ b/doc/aug_language.txt @@ -0,0 +1,4 @@ + +The Aesop Programming Language +============================== + diff --git a/doc/aug_preface.txt b/doc/aug_preface.txt new file mode 100644 index 0000000..88d1fcb --- /dev/null +++ b/doc/aug_preface.txt @@ -0,0 +1,64 @@ + +[preface] +Preface +========= + +This document is the aesop user guide. It describes how to obtain, build and +install the aesop language. In addition, it describes how to program using +aesop. + + +Latest version of this document +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +This document can be found in the aesop distribution, +which can be downloaded from http://trac.mcs.anl.gov/projects/aesop. + + +Contacting Us +~~~~~~~~~~~~~ + +Aesop Online +^^^^^^^^^^^^ + +The aesop home page is located at http://trac.mcs.anl.gov/projects/aesop. +Please report aesop issues (for this document or the aesop translator) and +feature requests at http://trac.mcs.anl.gov/projects/aesop/newticket. + +By Email +^^^^^^^^ +For other questions and concerns, the aesop developers can be contacted +at mailto:[email protected][[email protected]]. + +Conventions and notations +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Source code and shell commands +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Example source code, or example commands are rendered as follows: + +---- +printf ("Example code\n"); +---- + +Implementation-specific Behavior +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +It is important to differentiate between the _aesop language_ and the way this +language is currently implemented by the _aesop translator_. The aesop language +leaves certain aspects open. For these cases, the behavior as implemented by the +current version of the aesop translator might change in future versions. +In this document implementation-specific behavior will be indicated as shown +below. + +.Implementation Specific Behavior +[NOTE] +===== +Implementation-specific information. +===== +// ------------------------------------------------------------------------- +// ------------------------------------------------------------------------- +// ------------------------------------------------------------------------- +// ------------------------------------------------------------------------- + + diff --git a/doc/aug_standard.txt b/doc/aug_standard.txt new file mode 100644 index 0000000..6334a23 --- /dev/null +++ b/doc/aug_standard.txt @@ -0,0 +1,263 @@ + +The Aesop Standard Library +========================== + +Aesop System Interfaces and Tools +---------------------------------- + + +Configuration Interface +~~~~~~~~~~~~~~~~~~~~~~~ + + + +Debugging +~~~~~~~~~~ + +// TODO: talk about problem using gdb + + + +The code injected by the aesop translator supports writing tracing +information to `stderr`. + +The following components can be traced: + +[horizontal] +*blocking*:: Outputs when a blocking call is initiated and finished. + +*cancel*:: Outputs information regarding cancellation of blocking calls. + +*pbranch*:: Tracks the creation and completion of pbranches. + +To enable or disable tracing, use the following call: + +---- +int aesop_set_debugging (const char * component, int value); +---- + +Component can be either on of the following strings: + +* "ae_blocking" +* "ae_pbranch" +* "ae_cancel" + +Value should be 0 to disable, or 1 to enable tracing. + + +Standard Aesop modules +----------------------- + +The following functions are bundled with the aesop distribution. + +Timer +~~~~~~ + +Header: `triton.timer.hae` + + +---- +int aesop_timer_init(void); +void aesop_timer_finalize(void); +----- + +Before using any other timer function, the application is responsible for +calling `aesop_timer_init`. It is safe to call init more than once, as long +as one call to `aesop_timer_finalize` is made for every call to +`aesop_timer_init`. + + +----- +__blocking int aesop_timer(int millisecs); +---- + +The `aesop_timer` function will sleep for the given number of milliseconds. +The functions returns 0 on success, `-ECANCELED` if canceled before the sleep +time is over. + +Socket +~~~~~~ + +Header: `aesocket.hae` + +----- +int aesocket_init (void); +int aesocket_finalize (void); +---- + +Module initialization functions. + + +---- +__blocking int aesocket_accept( + int sockfd, + struct sockaddr *addr, + socklen_t * addrlen, + int *newfd, + int * err); +---- + +The aesop version of the accept system call. +Unlike the system call, the descriptor for the new connection is returned in +`*newfd`, while an error, if any, is returned in `*err`. +The function returns `AE_SUCCESS` when a new connection is accepted, +`AE_ERR_CANCELED` if the call was canceled and `AE_ERR_OTHER` if a system call +error occurred (returned in `*err`) occurred. + + + +----- +__blocking int aesocket_read( + int fd, + void *buf, + size_t count, + int *ret, + int * err); +---- +Read `count` bytes from the given socket. This call will not return +until an error occurred or at `count` bytes were read from the socket. +The function returns `AE_SUCCESS` if the requested number of bytes was read, +`AE_ERR_CANCELED` if the call was canceled and `AE_ERR_OTHER` if another error +occured, in which case `*err` is set to the POSIX error code. The number of +bytes read into `buf` is returned in `*ret`. + + + +---- +__blocking int aesocket_write( + int fd, + const void *buf, + size_t count, + int *ret, + int * err); +---- +As `aesocket_read`, but writes data to the socket instead. + +---- +__blocking int aesocket_ready (int fd, int flags, int * err); +---- + +The `aesocket_ready` call waits until the passed in descriptor is ready to +perform the action specified in `flags`. +`Flags` can be a combination of `AESOCKET_READ` or `AESOCKET_WRITE`. +The function returns `AE_ERR_CANCELED` when canceled, `AE_ERR_OTHER` when an +error was returned by the underlying system call, and `AE_SUCCESS` otherwise. +In case of `AE_ERR_OTHER`, the error code is stored in `*err`. + +This function is used internally to implement the `aesocket_read`, +`aesocket_write` and `aesocket_accept` functions. + + + + +File +~~~~ + +Header: `aefile.hae` + +---- +int aefile_init(void); +void aefile_finalize(void); +---- +As with the other code modules, the init function needs to be called before +calling any of the functions below. + + + +---- +__blocking ssize_t aefile_pwrite(int fd, const void *buf, size_t count, off_t offset); +__blocking ssize_t aefile_pread(int fd, void *buf, size_t count, off_t offset); +__blocking int aefile_fsync(int fd); +__blocking int aefile_fdatasync(int fd); +__blocking int aefile_ftruncate(int fd, off_t length); +__blocking int aefile_unlink(const char *pathname); +---- +These are aesop versions of the regular `pwrite`, `pread`, `fsync`, +`fdatasync`, `ftruncate` and `unlink` functions. + +[NOTE] +==== +Currently, these functions are implemented using a thread which calls the +regular I/O function. At this point, these functions cannot be cancelled. +==== + + +ResourceBuilder +~~~~~~~~~~~~~~~ + +Header: `resourcebuilder.hae` + +---- +void rb_slot_initialize (rb_slot_t * slot); +---- + +`rb_slot_t` is an opaque datatype. +Prepare a slot for using with the `rb_slot_capture` function. + + +---- +__blocking int rb_slot_capture (rb_slot_t * slot); +---- + +This call will suspend execution until the call is cancelled or until +`rb_slot_complete` is called on the slot. A slot only supports a single +capture call (i.e. it is illegal to call capture on a slot that is already +captured). When the call is completed by a call to `rb_slot_complete`, this +function returns `AE_SUCCESS`, and `AE_ERR_CANCELED` when the call returns due +to a cancellation request. + +After a call to this function, the slot needs to be destroyed (using +`rb_slot_destroy` and reinitialized before it can be used again. + +---- +int rb_slot_complete (rb_slot_t * slot); +---- + +Release a captured slot. This call returns `AE_SUCCESS` if it successfully +released a `rb_slot_capture` call on the slot. If the slot was not active (for +example because it was already cancelled), an unspecified aesop error code is +returned. + +---- +void rb_slot_destroy (rb_slot_t * slot); +---- + +Free resources associated with the slot. The slot must be inactive. It is +illegal to call this function on a slot that is currently captured. + + +[TIP] +==== +The ResourceBuilder functions provide a low level toolkit used to build higher +level code. For example, the ResourceBuilder is used to implement the aesop +socket functions. ResourceBuilder is also a good basis for building +synchronization primitives, such as mutexes and semaphores. +==== + + +thread +~~~~~~ + +---- +int aethread_init(void); +void aethread_finalize(void); +---- + +---- +struct aethread_group* aethread_create_group_pool(int size); +void aethread_destroy_group(struct aethread_group* group); +---- + + +---- +__blocking int aethread_hint(struct aethread_group* group); +---- + + +[NOTE] +==== +Like ResourceBuilder, the thread functionality is used as a tool to implement +other functions. See <<ref-thread>> for an example. +==== + + diff --git a/doc/module.mk.in b/doc/module.mk.in index 979af15..ffde779 100644 --- a/doc/module.mk.in +++ b/doc/module.mk.in @@ -2,3 +2,8 @@ ASCIIDOCSRC += doc/aesop-user-guide.txt \ doc/aesop-performance.txt \ doc/aesop-pbranch-cancel.txt +doc/aesop-user-guide.pdf: doc/aug_preface.txt \ + doc/aug_introduction.txt \ + doc/aug_language.txt \ + doc/aug_external.txt \ + doc/aug_standard.txt hooks/post-receive -- aesop Repository

1 0

aesop Repository branch, master, updated. ee08819538bcbb4be377f2d30c88c5aeaaa4fdce
by noreply＠mcs.anl.gov 24 Feb '12

24 Feb '12

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 "aesop Repository". The branch, master has been updated via ee08819538bcbb4be377f2d30c88c5aeaaa4fdce (commit) from 9d1120610c94180a458db02d632fb52cd24cdf32 (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 ee08819538bcbb4be377f2d30c88c5aeaaa4fdce Author: Phil Carns <carns(a)mcs.anl.gov> Date: Fri Feb 24 17:11:35 2012 -0500 updated code complexity table ----------------------------------------------------------------------- Summary of changes: doc/aesop-performance.txt | 10 ++++++---- 1 files changed, 6 insertions(+), 4 deletions(-) Diff of changes: diff --git a/doc/aesop-performance.txt b/doc/aesop-performance.txt index f50c5d8..850df4a 100644 --- a/doc/aesop-performance.txt +++ b/doc/aesop-performance.txt @@ -365,10 +365,12 @@ set of complexity metrics. [cols="3,1,1,1", options="header"] |============================ | Server Implementation | CC | Mod. CC | SLOC -| aesop | 15 | 10 | 171 -| thread | 17 | 12 | 179 -| thread pool | 29 | 23 | 292 -| event | 26 | 21 | 328 +| aesop | 16 | 11 | 179 +| thread-per-client | 17 | 12 | 182 +| thread-per-client-nb | 17 | 12 | 184 +| thread-per-op | 22 | 17 | 249 +| thread-pool | 32 | 26 | 313 +| event | 28 | 23 | 341 |============================ // @TODO: Need to update the table with other forms of threading hooks/post-receive -- aesop Repository

1 0

aesop Repository branch, master, updated. 9d1120610c94180a458db02d632fb52cd24cdf32
by noreply＠mcs.anl.gov 23 Feb '12

23 Feb '12

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 "aesop Repository". The branch, master has been updated via 9d1120610c94180a458db02d632fb52cd24cdf32 (commit) from b9972704b7601a3f95a90baa2bb0e430c7b8b2e7 (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 9d1120610c94180a458db02d632fb52cd24cdf32 Author: Dries Kimpe <dkimpe(a)mcs.anl.gov> Date: Thu Feb 23 23:43:27 2012 -0600 Make aesocket naming consistent (done->finalize) ----------------------------------------------------------------------- Summary of changes: src/socket/aesocket.ae | 2 +- src/socket/aesocket.hae | 2 +- src/socket/test/simple.ae | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) Diff of changes: diff --git a/src/socket/aesocket.ae b/src/socket/aesocket.ae index f0a14c6..1a657e4 100644 --- a/src/socket/aesocket.ae +++ b/src/socket/aesocket.ae @@ -111,7 +111,7 @@ int aesocket_init (void) return AE_SUCCESS; } -int aesocket_done (void) +int aesocket_finalize (void) { ae_mutex_lock (&mutex); if (0 == --refcount) diff --git a/src/socket/aesocket.hae b/src/socket/aesocket.hae index 503b1a8..55db9ac 100644 --- a/src/socket/aesocket.hae +++ b/src/socket/aesocket.hae @@ -20,7 +20,7 @@ int aesocket_init (void); /** * Inform the socket module it is no longer needed. */ -int aesocket_done (void); +int aesocket_finalize (void); /** diff --git a/src/socket/test/simple.ae b/src/socket/test/simple.ae index 4fc78be..2a68033 100644 --- a/src/socket/test/simple.ae +++ b/src/socket/test/simple.ae @@ -166,7 +166,7 @@ static __blocking int dotest (int argc, char ** args) aesocket_init (); test1 (); test2 (); - aesocket_done (); + aesocket_finalize (); return 0; } hooks/post-receive -- aesop Repository

1 0

aesop Repository branch, master, updated. b9972704b7601a3f95a90baa2bb0e430c7b8b2e7
by noreply＠mcs.anl.gov 23 Feb '12

23 Feb '12

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 "aesop Repository". The branch, master has been updated via b9972704b7601a3f95a90baa2bb0e430c7b8b2e7 (commit) from e1511e509210b3ab431087c36dab4952333f5775 (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 b9972704b7601a3f95a90baa2bb0e430c7b8b2e7 Author: Dries Kimpe <dkimpe(a)mcs.anl.gov> Date: Thu Feb 23 23:21:02 2012 -0600 Rename triton_timer to aesop_timer ----------------------------------------------------------------------- Summary of changes: ae-init.c | 4 +- aesop-support.hae | 2 +- parser/tests/blocking/cancel-pbranch-loop.ae | 4 +- parser/tests/blocking/cancel-pbranch1.ae | 8 ++-- parser/tests/blocking/cancel-pbranch2.ae | 2 +- parser/tests/blocking/cancel-pbranch3.ae | 6 ++-- .../blocking/lonely-pbranch-variable-scope.ae | 4 +- parser/tests/blocking/lonely-pbranch.ae | 2 +- parser/tests/blocking/lonely-pbranch2.ae | 2 +- parser/tests/blocking/lonely-pbranch3.ae | 2 +- parser/tests/blocking/lonely-pbranch4.ae | 2 +- resources/thread/test/aethread-cancel.ae | 2 +- resources/timer/test/pthread-compare.ae | 2 +- resources/timer/test/timer-cancel.ae | 4 +- resources/timer/test/timer1.ae | 6 ++-- resources/timer/test/timer2.ae | 4 +- resources/timer/timer.c | 36 ++++++++++---------- resources/timer/timer.hae | 6 ++-- src/socket/test/simple.ae | 4 +- tests/test-hints.ae | 2 +- 20 files changed, 52 insertions(+), 52 deletions(-) Diff of changes: diff --git a/ae-init.c b/ae-init.c index bb8f914..2fb9734 100644 --- a/ae-init.c +++ b/ae-init.c @@ -1,11 +1,11 @@ #include "ae-init.h" -__attribute__((constructor)) void triton_timer_init_register(void); +__attribute__((constructor)) void aesop_timer_init_register(void); __attribute__((constructor)) void triton_aethread_init_register(void); int ae_init (void) { /* Call the constructor functions here */ - triton_timer_init_register (); + aesop_timer_init_register (); triton_aethread_init_register (); } diff --git a/aesop-support.hae b/aesop-support.hae index a6bd9dd..012f89e 100644 --- a/aesop-support.hae +++ b/aesop-support.hae @@ -15,7 +15,7 @@ if (aesop_count_branches() < 2) { \ break; \ } \ - __ae_cancel_branches_wait_ret = triton_timer(2); \ + __ae_cancel_branches_wait_ret = aesop_timer(2); \ } while (__ae_cancel_branches_wait_ret == 0); \ } diff --git a/parser/tests/blocking/cancel-pbranch-loop.ae b/parser/tests/blocking/cancel-pbranch-loop.ae index c71287a..3a4582b 100644 --- a/parser/tests/blocking/cancel-pbranch-loop.ae +++ b/parser/tests/blocking/cancel-pbranch-loop.ae @@ -15,7 +15,7 @@ static __blocking void run_test(void) while(1) { - ret = triton_timer(4); + ret = aesop_timer(4); if(ret != 0) { break; @@ -25,7 +25,7 @@ static __blocking void run_test(void) pbranch { - triton_timer(5); + aesop_timer(5); /* cancel the other pbranch */ printf("pbranch2: calling aesop_cancel_branches_wait().\n"); diff --git a/parser/tests/blocking/cancel-pbranch1.ae b/parser/tests/blocking/cancel-pbranch1.ae index fbe7500..2b04650 100644 --- a/parser/tests/blocking/cancel-pbranch1.ae +++ b/parser/tests/blocking/cancel-pbranch1.ae @@ -51,7 +51,7 @@ static __blocking void run_test(void) { /* wait 1 second to let the tctest1 call finish */ printf("pbranch2: setting timer for 1 second.\n"); - triton_timer(1000); + aesop_timer(1000); printf("pbranch2: timer done.\n"); /* cancel the other pbranch */ printf("pbranch2: calling aesop_cancel_branches_wait().\n"); @@ -76,7 +76,7 @@ static __blocking void run_test(void) { /* wait 1 second to let the tctest1 call finish */ printf("pbranch2: setting timer for 1 second.\n"); - triton_timer(1000); + aesop_timer(1000); printf("pbranch2: timer done.\n"); /* cancel the other pbranch */ printf("pbranch2: calling aesop_cancel_branches_wait().\n"); @@ -104,7 +104,7 @@ static __blocking void run_test(void) { /* wait 1 second to let the tctest1 call finish */ printf("pbranch2: setting timer for 1 second.\n"); - triton_timer(1000); + aesop_timer(1000); printf("pbranch2: timer done.\n"); /* cancel the other pbranch */ printf("pbranch2: calling aesop_cancel_branches_wait().\n"); @@ -138,7 +138,7 @@ static __blocking void run_test(void) { /* wait 1 second to let the tctest1 call finish */ printf("pbranch2: setting timer for 1 second.\n"); - triton_timer(1000); + aesop_timer(1000); printf("pbranch2: timer done.\n"); /* cancel the other pbranch */ printf("pbranch2: calling aesop_cancel_branches_wait().\n"); diff --git a/parser/tests/blocking/cancel-pbranch2.ae b/parser/tests/blocking/cancel-pbranch2.ae index 83f3938..92a56bc 100644 --- a/parser/tests/blocking/cancel-pbranch2.ae +++ b/parser/tests/blocking/cancel-pbranch2.ae @@ -33,7 +33,7 @@ static __blocking void run_test(void) { /* wait 1 second to let the tctest1 call finish */ printf("pbranch2: setting timer for 1 second.\n"); - triton_timer(1000); + aesop_timer(1000); printf("pbranch2: timer done.\n"); /* cancel the other pbranch */ printf("pbranch2: calling aesop_cancel_branches_wait().\n"); diff --git a/parser/tests/blocking/cancel-pbranch3.ae b/parser/tests/blocking/cancel-pbranch3.ae index 694af3d..502bf4e 100644 --- a/parser/tests/blocking/cancel-pbranch3.ae +++ b/parser/tests/blocking/cancel-pbranch3.ae @@ -14,9 +14,9 @@ static __blocking void run_test(void) { pbranch { - printf("pbranch1: calling triton_timer().\n"); - triton_timer(5); - printf("pbranch1: finished triton_timer().\n"); + printf("pbranch1: calling aesop_timer().\n"); + aesop_timer(5); + printf("pbranch1: finished aesop_timer().\n"); sleep(5); } diff --git a/parser/tests/blocking/lonely-pbranch-variable-scope.ae b/parser/tests/blocking/lonely-pbranch-variable-scope.ae index 573a244..e55aef1 100644 --- a/parser/tests/blocking/lonely-pbranch-variable-scope.ae +++ b/parser/tests/blocking/lonely-pbranch-variable-scope.ae @@ -28,7 +28,7 @@ static __blocking void lonely_pbranch(void) /* start a timer to make sure that the pbranch is * still active after this function returns */ - ret = triton_timer(2000); + ret = aesop_timer(2000); if(ret != 0) { printf("Error in branch 1 while sleeping\n"); @@ -55,7 +55,7 @@ __blocking int aesop_main(int argc, char **argv) lonely_pbranch(); /* start a timer to wait for the lonely pbranch to finish */ printf("Sleeping 5 seconds to wait for pbranch to finish.\n"); - triton_timer(5000); + aesop_timer(5000); printf("Test complete.\n"); return 0; } diff --git a/parser/tests/blocking/lonely-pbranch.ae b/parser/tests/blocking/lonely-pbranch.ae index 8626add..9a7eacc 100644 --- a/parser/tests/blocking/lonely-pbranch.ae +++ b/parser/tests/blocking/lonely-pbranch.ae @@ -24,7 +24,7 @@ static __blocking void lonely_pbranch(void) printf("Error in branch 1.\n"); } - ret = triton_timer(2000); + ret = aesop_timer(2000); if(ret != 0) { printf("Error in branch 1 while sleeping\n"); diff --git a/parser/tests/blocking/lonely-pbranch2.ae b/parser/tests/blocking/lonely-pbranch2.ae index 04d05cc..52f8b32 100644 --- a/parser/tests/blocking/lonely-pbranch2.ae +++ b/parser/tests/blocking/lonely-pbranch2.ae @@ -30,7 +30,7 @@ static __blocking void lonely_pbranch(void) printf("Error in branch 1.\n"); } - ret = triton_timer(2000); + ret = aesop_timer(2000); if(ret != 0) { printf("Error in branch 1 while sleeping\n"); diff --git a/parser/tests/blocking/lonely-pbranch3.ae b/parser/tests/blocking/lonely-pbranch3.ae index b5a32ba..e101276 100644 --- a/parser/tests/blocking/lonely-pbranch3.ae +++ b/parser/tests/blocking/lonely-pbranch3.ae @@ -6,7 +6,7 @@ static __blocking void noop(void) { - /* triton_timer(10); */ + /* aesop_timer(10); */ return; } diff --git a/parser/tests/blocking/lonely-pbranch4.ae b/parser/tests/blocking/lonely-pbranch4.ae index 2c8d911..fc6371c 100644 --- a/parser/tests/blocking/lonely-pbranch4.ae +++ b/parser/tests/blocking/lonely-pbranch4.ae @@ -31,7 +31,7 @@ static __blocking void lonely_pbranch(void) printf("Error in branch 1.\n"); } - ret = triton_timer(2000); + ret = aesop_timer(2000); if(ret != 0) { printf("Error in branch 1 while sleeping\n"); diff --git a/resources/thread/test/aethread-cancel.ae b/resources/thread/test/aethread-cancel.ae index 4f8cba8..17c28a8 100644 --- a/resources/thread/test/aethread-cancel.ae +++ b/resources/thread/test/aethread-cancel.ae @@ -66,7 +66,7 @@ static __blocking int dotest(void) /* wait 100 milliseconds to make sure that some threads begin * service */ - triton_timer(100); + aesop_timer(100); /* cancel what we can */ aesop_cancel_branches_wait(); diff --git a/resources/timer/test/pthread-compare.ae b/resources/timer/test/pthread-compare.ae index a3f2321..9dbba25 100644 --- a/resources/timer/test/pthread-compare.ae +++ b/resources/timer/test/pthread-compare.ae @@ -16,7 +16,7 @@ static __blocking int triton_dosleep(void) { pbranch { - triton_timer(1000); + aesop_timer(1000); } } } diff --git a/resources/timer/test/timer-cancel.ae b/resources/timer/test/timer-cancel.ae index f38c6a5..647bdff 100644 --- a/resources/timer/test/timer-cancel.ae +++ b/resources/timer/test/timer-cancel.ae @@ -11,14 +11,14 @@ static __blocking int dotimer(void) pbranch { printf("sleeping for 10 s\n"); - triton_timer(10000); + aesop_timer(10000); printf("10 s done.\n"); } pbranch { printf("sleeping for 1 s\n"); - triton_timer(1000); + aesop_timer(1000); printf("1 s done.\n"); /* shut down the other timer */ diff --git a/resources/timer/test/timer1.ae b/resources/timer/test/timer1.ae index 77a5b63..a8183ca 100644 --- a/resources/timer/test/timer1.ae +++ b/resources/timer/test/timer1.ae @@ -10,21 +10,21 @@ static __blocking int dotimer(void) pbranch { printf("sleeping for 100 ms\n"); - triton_timer(100); + aesop_timer(100); printf("100 ms done.\n"); } pbranch { printf("sleeping for 1000 ms\n"); - triton_timer(1000); + aesop_timer(1000); printf("1000 ms done.\n"); } pbranch { printf("sleeping for 10 ms\n"); - triton_timer(10); + aesop_timer(10); printf("10 ms done.\n"); } } diff --git a/resources/timer/test/timer2.ae b/resources/timer/test/timer2.ae index b62bc90..d18b139 100644 --- a/resources/timer/test/timer2.ae +++ b/resources/timer/test/timer2.ae @@ -17,7 +17,7 @@ static __blocking int receiver() while(!exit_loop) { printf("recving...\n"); - triton_timer(100); + aesop_timer(100); } } pbranch @@ -25,7 +25,7 @@ static __blocking int receiver() while(!exit_loop) { printf("sleeping...\n"); - triton_timer(100); + aesop_timer(100); if (i++ == 10) { exit_loop = 1; diff --git a/resources/timer/timer.c b/resources/timer/timer.c index 4904a94..bc8df00 100644 --- a/resources/timer/timer.c +++ b/resources/timer/timer.c @@ -24,7 +24,7 @@ #define TIMER_DEFAULT_SIZE 1024 static ae_opcache_t timer_opcache = NULL; -static int triton_timer_resource_id; +static int aesop_timer_resource_id; static ev_timer timer_watcher; static struct ev_loop* timer_loop = NULL; static void timer_cb(EV_P_ ev_timer *w, int revents); @@ -44,7 +44,7 @@ static triton_mutex_t timer_mutex = TRITON_MUTEX_INITIALIZER; static ae_ops_t timer_oplist; static ae_ops_t cancel_oplist; -ae_define_post(int, triton_timer, int millisecs) +ae_define_post(int, aesop_timer, int millisecs) { struct timeval adjust, now; int ret; @@ -59,7 +59,7 @@ ae_define_post(int, triton_timer, int millisecs) ae_op_fill(op); top = ae_op_entry(op, struct timer_op, op); - top->op_id = ae_id_gen(triton_timer_resource_id, (uintptr_t) op); + top->op_id = ae_id_gen(aesop_timer_resource_id, (uintptr_t) op); top->ret = 0; top->milliseconds = millisecs; @@ -99,12 +99,12 @@ ae_define_post(int, triton_timer, int millisecs) triton_mutex_unlock(&timer_mutex); - ae_resource_request_poll(op->ctx, triton_timer_resource_id); + ae_resource_request_poll(op->ctx, aesop_timer_resource_id); return AE_SUCCESS; } -static int triton_timer_poll(ae_context_t context) +static int aesop_timer_poll(ae_context_t context) { struct ae_op *op; struct ae_op *op_head; @@ -163,7 +163,7 @@ static int triton_timer_poll(ae_context_t context) return AE_SUCCESS; } -static int triton_timer_cancel(ae_context_t triton_ctx, ae_op_id_t op_id) +static int aesop_timer_cancel(ae_context_t triton_ctx, ae_op_id_t op_id) { /* TODO: do we have to check for races here (trying to cancel an ae_op * that no longer exists) , or does aesop do that for us? @@ -179,7 +179,7 @@ static int triton_timer_cancel(ae_context_t triton_ctx, ae_op_id_t op_id) triton_mutex_lock(&timer_mutex); op = intptr2op (ae_id_lookup(op_id, &resource_id)); - assert(resource_id == triton_timer_resource_id); + assert(resource_id == aesop_timer_resource_id); /* should still be in an op list */ if(!ae_ops_exists(&timer_oplist, &op->link)) @@ -207,27 +207,27 @@ static int triton_timer_cancel(ae_context_t triton_ctx, ae_op_id_t op_id) triton_mutex_unlock(&timer_mutex); /* request a poll for aesop to harvest the cancelled timer */ - ae_resource_request_poll(ctx, triton_timer_resource_id); + ae_resource_request_poll(ctx, aesop_timer_resource_id); return AE_SUCCESS; } -struct ae_resource triton_timer_resource = +struct ae_resource aesop_timer_resource = { .resource_name = RESOURCE_NAME, - .poll_context = triton_timer_poll, - .cancel = triton_timer_cancel, + .poll_context = aesop_timer_poll, + .cancel = aesop_timer_cancel, .config_array = NULL }; -__attribute__((constructor)) void triton_timer_init_register(void); +__attribute__((constructor)) void aesop_timer_init_register(void); -__attribute__((constructor)) void triton_timer_init_register(void) +__attribute__((constructor)) void aesop_timer_init_register(void) { - ae_resource_init_register("timer", triton_timer_init, triton_timer_finalize); + ae_resource_init_register("timer", aesop_timer_init, aesop_timer_finalize); } -int triton_timer_init(void) +int aesop_timer_init(void) { int ret; @@ -242,12 +242,12 @@ int triton_timer_init(void) return AE_ERR_SYSTEM; } - return ae_resource_register(&triton_timer_resource, &triton_timer_resource_id); + return ae_resource_register(&aesop_timer_resource, &aesop_timer_resource_id); } -void triton_timer_finalize(void) +void aesop_timer_finalize(void) { - ae_resource_unregister(triton_timer_resource_id); + ae_resource_unregister(aesop_timer_resource_id); ae_opcache_destroy(timer_opcache); } diff --git a/resources/timer/timer.hae b/resources/timer/timer.hae index 41c70d4..eee04b5 100644 --- a/resources/timer/timer.hae +++ b/resources/timer/timer.hae @@ -9,10 +9,10 @@ * run a timer for the specified number of milliseconds * \return 0 on success, -ECANCELED if canceled */ -__blocking int triton_timer(int millisecs); +__blocking int aesop_timer(int millisecs); -int triton_timer_init(void); -void triton_timer_finalize(void); +int aesop_timer_init(void); +void aesop_timer_finalize(void); #endif diff --git a/src/socket/test/simple.ae b/src/socket/test/simple.ae index c3b39c6..4fc78be 100644 --- a/src/socket/test/simple.ae +++ b/src/socket/test/simple.ae @@ -24,7 +24,7 @@ static __blocking int test1 () { /* pbranch { - tret = triton_timer (100); + tret = aesop_timer (100); assert (tret != AE_SUCCESS && "File did not become read??"); // aesop_cancel_branches_wait (); } */ @@ -141,7 +141,7 @@ static __blocking int test2 () pbranch { int ret; - ret = triton_timer (10000); + ret = aesop_timer (10000); if (ret == AE_SUCCESS) { printf ("Cancelling!"); diff --git a/tests/test-hints.ae b/tests/test-hints.ae index 5554a56..28b9de6 100644 --- a/tests/test-hints.ae +++ b/tests/test-hints.ae @@ -10,7 +10,7 @@ __blocking void do_blocking3(void) ret = aesop_hints_get("aesop.test.sleepy_time", sizeof(sleep), &sleep); assert(ret == 0); - triton_timer(sleep); + aesop_timer(sleep); } __blocking void do_blocking2(void) hooks/post-receive -- aesop Repository

1 0

aesop Repository branch, master, updated. e1511e509210b3ab431087c36dab4952333f5775
by noreply＠mcs.anl.gov 23 Feb '12

23 Feb '12

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 "aesop Repository". The branch, master has been updated via e1511e509210b3ab431087c36dab4952333f5775 (commit) from 79dc4925c84e40e14935f3cef91cde24cc5535d7 (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 e1511e509210b3ab431087c36dab4952333f5775 Author: Dries Kimpe <dkimpe(a)mcs.anl.gov> Date: Thu Feb 23 16:18:03 2012 -0600 Correct read performance figure. ----------------------------------------------------------------------- Summary of changes: doc/aesop-performance.txt | 4 ++-- doc/fig/read-hist.png | Bin 5226 -> 4950 bytes 2 files changed, 2 insertions(+), 2 deletions(-) Diff of changes: diff --git a/doc/aesop-performance.txt b/doc/aesop-performance.txt index 1f53e6c..f50c5d8 100644 --- a/doc/aesop-performance.txt +++ b/doc/aesop-performance.txt @@ -87,8 +87,8 @@ __blocking int test (void) ---- So, in the example above, even though the test will return without waiting for -the pbranch to complete, it's stack variables (var in this case) will consume -memory until the pbranch returns. +the pbranch to complete, it's stack variables (`var` in this case) will +consume memory until the pbranch returns. //========================================================================= diff --git a/doc/fig/read-hist.png b/doc/fig/read-hist.png index 5ed1196..cf14290 100644 Binary files a/doc/fig/read-hist.png and b/doc/fig/read-hist.png differ hooks/post-receive -- aesop Repository

1 0

aesop Repository branch, master, updated. 79dc4925c84e40e14935f3cef91cde24cc5535d7
by noreply＠mcs.anl.gov 23 Feb '12

23 Feb '12

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 "aesop Repository". The branch, master has been updated via 79dc4925c84e40e14935f3cef91cde24cc5535d7 (commit) via 52805506a3dfb472e691e6d12f0537f8642ba14f (commit) from e64d7c91970c0a9315016b5729a3b2ea7a53818e (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 79dc4925c84e40e14935f3cef91cde24cc5535d7 Author: Dries Kimpe <dkimpe(a)mcs.anl.gov> Date: Thu Feb 23 15:42:02 2012 -0600 Aesop performance document commit 52805506a3dfb472e691e6d12f0537f8642ba14f Author: Dries Kimpe <dkimpe(a)mcs.anl.gov> Date: Wed Feb 22 16:40:46 2012 -0600 Update blocking overhead benchmark ----------------------------------------------------------------------- Summary of changes: doc/aesop-performance.txt | 463 +++++++++++++++++++++++++++++++++++++++++++ doc/fig/read-hist.png | Bin 0 -> 5226 bytes doc/fig/read-mem.png | Bin 0 -> 4564 bytes doc/fig/read-null-hist.png | Bin 0 -> 4877 bytes doc/fig/read-null-mem.png | Bin 0 -> 5055 bytes doc/fig/read-null.png | Bin 0 -> 6700 bytes doc/fig/read.png | Bin 0 -> 5818 bytes doc/fig/write-hist.png | Bin 0 -> 4795 bytes doc/fig/write-mem.png | Bin 0 -> 4562 bytes doc/fig/write-null-hist.png | Bin 0 -> 5022 bytes doc/fig/write-null-mem.png | Bin 0 -> 4594 bytes doc/fig/write-null.png | Bin 0 -> 6410 bytes doc/fig/write.png | Bin 0 -> 5494 bytes tests/blocking-overhead.ae | 93 ++++++--- 14 files changed, 525 insertions(+), 31 deletions(-) create mode 100644 doc/fig/read-hist.png create mode 100644 doc/fig/read-mem.png create mode 100644 doc/fig/read-null-hist.png create mode 100644 doc/fig/read-null-mem.png create mode 100644 doc/fig/read-null.png create mode 100644 doc/fig/read.png create mode 100644 doc/fig/write-hist.png create mode 100644 doc/fig/write-mem.png create mode 100644 doc/fig/write-null-hist.png create mode 100644 doc/fig/write-null-mem.png create mode 100644 doc/fig/write-null.png create mode 100644 doc/fig/write.png Diff of changes: diff --git a/doc/aesop-performance.txt b/doc/aesop-performance.txt index e69de29..1f53e6c 100644 --- a/doc/aesop-performance.txt +++ b/doc/aesop-performance.txt @@ -0,0 +1,463 @@ + +Aesop Performance Tuning Guide +============================== + +== Introduction + +This document describes a number of tips and techniques to speed up code +development using aesop. This includes the time required to execute the source +to source translator as well as the runtime efficiency of the generated code. + +//========================================================================= +== Translation Performance +//========================================================================= + +=== Parallel Make + +It is possible to speed up the translation of aesop files by using the `-jn` +option to make, replacing `n` by the desired number of concurrent jobs. + +=== CCache + +At this time, there are a number of issues blocking the use of ccache in +combination with the aesop source to source translator (either to cache the +translation or to cache the compilation of the generated C source code). + +A first issue is related to incorrect handling of compiler names in the build +system, causing the build to fail if the compiler is set to `ccache gcc`. + +The second issue stems from the fact that aesop introduces additional +dependencies which are not understood by ccache. Therefore, subtly failures +would be introduced when aesop is updated and the cache is not manually +cleared. + +Given these issues, at this point it is not recommended to use ccache in +combination with aesop. However, both issues can be resolved in a later +aesop release (see ticket #137 and #200 in the triton repository). + + +//========================================================================= +== Runtime Memory Efficiency +//========================================================================= + +This section examines the memory efficiency of the translated aesop code. + +=== Function arguments and stack variables of blocking calls + +Aesop, in order to implement the additional functionality provided by blocking +calls, rewrites blocking calls when translating the aesop code to C code. +This translation introduces a certain amount of overhead, both in memory usage +and execution performance. This section focuses on memory overhead, +deferring the discussion of execution overhead to <<ref-blocking-runtime>>. + +The main memory overhead incurred by blocking functions originates from the +need to protect the logical state of the function while temporarily switching +to other functions. + +For example, stack variables are moved to the heap. As long as the blocking +function does not complete, the memory for these variables is not released. +Arguments to the function need to be relocated to the heap as well, +and so does the type returned from the function (if not void). + +In a normal C program, the items listed above consume stack space. In blocking +functions, these consume heap space instead. In addition, aesop internally +maintains a number of control structures. Pointers to these structures are +passed as function arguments to the blocking function, and consequently +consume stack space. Currently, aesop adds about 4 pointers and 2 integers to +each blocking function call. + + + + +=== Lonely pbranches + +A lonely pbranch will keep the enclosing scope alive (up to the function +scope) until the pbranch exits. + +.lonely pbranch scope +[source, C] +---- +__blocking int test (void) +{ + int var[10000]; + pbranch { + ... + } +} +---- + +So, in the example above, even though the test will return without waiting for +the pbranch to complete, it's stack variables (var in this case) will consume +memory until the pbranch returns. + + +//========================================================================= +== Runtime Execution Speed +//========================================================================= + +[[ref-blocking-runtime]] +=== Performance Implications of Blocking Calls + +While this isn't immediately visible from looking at the aesop source code, +blocking calls, when compared to a plain C function call, have extra overhead +due to the way they are transformed by the aesop compiler. The following +section highlights the sources of this overhead. + +==== Understanding Blocking Call Overhead + +===== State Management + +Most of the overhead is caused by the need to preserve the state +of the blocking call while execution (temporarily) switches to another +function. In order to preserve this state, the aesop compiler relocates all +function-scoped variables from the stack to the heap. +When entering a blocking function, heap memory needs to be allocated for these +variables. As allocating heap memory is much more time consuming than +allocating space on the stack, calling a blocking function is more expensive +than calling a regular function. + + + +===== Synchronization Overhead + +A second source of overhead originates from the multi-threaded nature of aesop +code. While aesop does not create any threads, many of the aesop resources +internally use threads. Therefore, the aesop compiler has to ensure that the +emitted code is multi-thread safe. For example, in the following code, +two pbranches might be executing concurrently using different threads. +Since these threads could both by modifying the pwait state simultaneously, +aesop +uses locks to serialize their access. Locks, and other synchronization +primitives account for most of the remaining performance difference between +blocking and regular function calls. + +.pwait synchronization +[source,C] +---- +pwait { + pbranch { + ... + } + pbranch { + ... + } +} +---- + + +[NOTE] +Currently, the aesop compiler uses a combination of atomic operations and +mutexes to maintain thread-safety. There is an ongoing effort to convert to +atomic operations where possible. + + +==== Quantifying Blocking Call Overhead + + +For this test, a regular and a blocking function are called in a loop. +By timing the total time required to complete the loop, an estimate of the +time needed to execute the function call is obtained. + +The results were obtained on an intel i7 CPU running at 2.7GHz, +using gcc 4.5.3 (using +-O2+), glibc 2.13-r4 and kernel 3.2.5. + +There are a number of different test configurations: + +.Test Results +[width="20%",cols="h,^,^,^,^,^,<,<",valign="middle",frame="topbot",options="header"] +|===== +1.2+<.^| Test 5+| Options 2+^.^| seconds/call + ^d| regular | blocking | malloc/free | mutex | opa | malloc | tcmalloc +| 1 | X | | | | | 2.24e-09 | 2.21e-09 +| 2 | | X | | | | 5.54e-08 | 3.62e-08 +| 3 | X | | X | | | 2.34e-08 | 1.62e-08 +| 4 | X | | X | X | | 3.78e-08 | 2.96e-08 +| 5 | X | | X | | X | 2.95e-08 | 2.02e-08 +|===== + +For test 1, a simple regular C function (i.e. not using `__blocking`) taking 2 +arguments is used. +Test 2 uses the same function, but this time the function is marked as +`__blocking`. + +Tests 3-5 were added to provide a better context for understanding the +magnitude of the blocking call overhead. For test 3, the function from test 1 +was taken but in the function body a single call to +malloc+ and +free+ was +added. Test 4 is the same as test 3, but also adds a call to lock and unlock +a mutex. Test 5 replaces the mutex by a single atomic operation +(compare-and-swap). + +As a way to study the effect of the malloc implementation, these tests were +also executed using a +tcmalloc+, an alternative memory allocator library. +The results for these are shown in the tcmalloc column. + +[TIP] +The progam used to obtain these results is in the repository: ++tests/blocking-overhead.ae+. + + + +//========================================================================= +== Case study: Implementing a small network server +//========================================================================= + +While micro-benchmarks can be useful, they often fail to capture the +complexity found in real applications. + +To provide a higher level evaluation, we compared the performance of a simple +network server programmed in aesop to that of the same server implemented in +C. We also quantified the code complexity of the aesop server, compared to the +different C versions. + +=== Server Description + +The example server listens on a TCP socket for incoming client connections. +Once a client connects, the server waits until a request is received or until +the client closes the connection. + +The server recognizes four different request types: + +*READ and WRITE*:: The server reads or writes a file specified by the client. + +*READ-NULL and WRITE-NULL*:: The same as READ and WRITE respectively, except +that the file read or write operations are omitted. The requested data +is still transferred over the network. + +The read-null and write-null cases attempt to determine the maximum network +bandwidth the server can sustain, by ensuring the disk operations are not a +bottleneck. + +.Server Request Handling +[graphviz] +-------- +digraph G +{ + subgraph I { + rank = same; + incoming [label="client connects", shape="box"]; + close [label="close connection"]; + } + + wait [label="receive request"]; + + incoming -> wait; + wait -> close [label="client closes connection"]; + wait -> read_1 [label = "READ"]; + wait -> readn_1 [label = "READ NULL"]; + wait -> write_1 [label = "WRITE"]; + wait -> writen_1 [label = "WRITE NULL"]; + + + + subgraph R { + read_1 [label="read from file"]; + read_2 [label="send data"]; + read_1 -> read_2 -> wait; + } + + subgraph W { + write_1 [label="receive data"]; + write_2 [label="write to file"]; + write_1 -> write_2 -> wait; + } + + subgraph RN { + readn_1 [label="send data"]; + readn_1 -> wait; + } + + subgraph WN { + writen_1 [label="receive data"]; + writen_1 -> wait; + } + + +} + +-------- + +==== Implementation Details + +The server as described above was implemented in 5 different ways. + +===== Explicit Threading + +The threaded server uses manual thread management to explicitly created or +destroy a thread in response to an incoming connection or request. +We used the `pthread` threading library. +For the threaded implementation, we distinguish between 4 different +variations. + + +[width="80%",cols=">.^1h,4",frame="none",grid="none"] +|========================================================= +| thread-per-client | +A thread is created when a client connects, and this +thread is dedicated to the connection. All requests from this connection will +be handled by the same thread. + +| | + + +| thread-per-client-nb | +The same as above, but in this case the thread calls +the _asynchronous_ versions of the `read` and `write` system calls. By +including this option, performance differences related to the asynchronous +nature of the system calls are highlighted. + +| | + +| thread-per-op | +In this mode, a thread is created for every incoming +request. After the request is completed, the thread is destroyed. + +| | + +|thread-pool | +As above, but when a thread has finished executing a request +it is returned to a pool and reused when a new request arrives. + +|============================================================= + +===== Explicit Event Handling + +For this version, _libev_ is used to implement an event-driven server. +At any given time, a number of different events can occur, the event loop +waits for one of the following events to occur: + +[horizontal] +*Accept*:: An new client connected to the server. The server will start an +attempt to read a request from the connection. +*Read*:: A read from a connection completed. +*Write*:: A write operation (writing data to a client) completed. + +In response to one of these events, the next step in handling the connection +will be started using an asynchronous call before going back to the main event +loop to wait for another event to occur. + +Note that this server implementation does not use create any threads, and only +utilizes a single core (though the operating system can still use multiple +cores to drive the network and disk). + +==== Aesop + +The aesop version, from a code point of view, most closely resembles the +_thread_per_client_ code. However, after translation, the resulting C code can +support the event model as well as a threaded model. + +The actual result will depend on the actual resource implementation. +(For more information about resources, see the aesop user guide). +It is important to point out that the choice between an event driven or +threaded approach is limited to the resource implementation, and that no +changes to the actual server code are required. + +The aesop code uses a lonely pbranch when a client connects. +The code within the lonely pbranch is a direct implementation of the flow +chart provided with the server description. + +=== Code Complexity + +As a measure for productivity, we investigated the code of each server using a +set of complexity metrics. + +.Implementation complexity analysis. +[[table-complex]] +[cols="3,1,1,1", options="header"] +|============================ +| Server Implementation | CC | Mod. CC | SLOC +| aesop | 15 | 10 | 171 +| thread | 17 | 12 | 179 +| thread pool | 29 | 23 | 292 +| event | 26 | 21 | 328 +|============================ + +// @TODO: Need to update the table with other forms of threading + +////// +\begin{table} +\small +\begin{center} +\caption{Complexity analysis for example servers} +\begin{tabular}{lrrr} +\hline +& CC & mod. CC & SLOC \\ +\hline +\hline +\end{tabular} +\label{tab:complexity} +\end{center} +\normalsize +\vspace{-.2in} +\end{table} +///// + +<<table-complex>> compares the code complexity of each implementation using McCabe +Cyclomatic Complexity (CC) <<McCabe>>, Modified McCabe Cyclomatic Complexity +(Mod. CC), and Source Lines of Code (SLOC). + +//TODO: reference the +//metrics and the tools that we used to collect them (pmccabe and sloccount). + +To simplify the comparison, error handling was excluded for all servers except +for assertions on expected return codes. The protocol definition (ie, +request and acknowledgement structs) as well as helper functions to loop +over send and receive were not counted in any of the implementations, as these +were similar in all four. + +Aesop and thread are very similar in terms of complexity, with the slight +increase in the thread model due to function calls needed to create and join +threads. + +Thread pool and event model are both much more complex than the thread or +aesop model. An additional complexity of the event model which is not +captured by these metrics is the fact that control flow is not preserved +across the processing of a given request. For example, servicing a write +operation requires 5 disconnected event handlers. So although the event +model appears less complex according to CC and mod. CC, qualitatively it is +significantly more challenging to develop. + + + +=== Performance Evaluation + +We evaluated the performance of our server implementation. +The same client was used for all server implementations. + +.Performance writing to server memory. +[[fig-write]] +image::fig/write-hist.png["Write"] + +.Performance reading from server memory. +[[fig-read]] +image::fig/read-hist.png["Read"] + +.Performance writing to disk. +[[fig-write-null]] +image::fig/write-null-hist.png["Writing to disk"] + +.Performance reading from disk. +[[fig-read-null]] +image::fig/read-null-hist.png["Reading from disk"] + +.Memory usage during the write test +[[fig-write-mem]] +image::fig/write-mem.png["Write test server memory usage"] + +.Memory usage during the read test +[[fig-read-mem]] +image::fig/read-mem.png["Read test server memory usage"] + +.Memory usage during the write-null test +[[fig-write-mem]] +image::fig/write-null-mem.png["Write-null test server memory usage"] + +.Memory usage during the read-null test +[[fig-read-mem]] +image::fig/read-null-mem.png["Read-null test server memory usage"] + + +== Bibliography + +[bibliography] +- [[[McCabe]]] McCabe, T.J. A Complexity Measure. In IEEE Transactions on + Software Engineering, vol.SE-2, no.4, pp. 308- 320, Dec. 1976. diff --git a/doc/fig/read-hist.png b/doc/fig/read-hist.png new file mode 100644 index 0000000..5ed1196 Binary files /dev/null and b/doc/fig/read-hist.png differ diff --git a/doc/fig/read-mem.png b/doc/fig/read-mem.png new file mode 100644 index 0000000..9e76e8c Binary files /dev/null and b/doc/fig/read-mem.png differ diff --git a/doc/fig/read-null-hist.png b/doc/fig/read-null-hist.png new file mode 100644 index 0000000..048f988 Binary files /dev/null and b/doc/fig/read-null-hist.png differ diff --git a/doc/fig/read-null-mem.png b/doc/fig/read-null-mem.png new file mode 100644 index 0000000..105f664 Binary files /dev/null and b/doc/fig/read-null-mem.png differ diff --git a/doc/fig/read-null.png b/doc/fig/read-null.png new file mode 100644 index 0000000..1f75427 Binary files /dev/null and b/doc/fig/read-null.png differ diff --git a/doc/fig/read.png b/doc/fig/read.png new file mode 100644 index 0000000..bed1524 Binary files /dev/null and b/doc/fig/read.png differ diff --git a/doc/fig/write-hist.png b/doc/fig/write-hist.png new file mode 100644 index 0000000..2db69be Binary files /dev/null and b/doc/fig/write-hist.png differ diff --git a/doc/fig/write-mem.png b/doc/fig/write-mem.png new file mode 100644 index 0000000..7947b19 Binary files /dev/null and b/doc/fig/write-mem.png differ diff --git a/doc/fig/write-null-hist.png b/doc/fig/write-null-hist.png new file mode 100644 index 0000000..e6bb934 Binary files /dev/null and b/doc/fig/write-null-hist.png differ diff --git a/doc/fig/write-null-mem.png b/doc/fig/write-null-mem.png new file mode 100644 index 0000000..137a995 Binary files /dev/null and b/doc/fig/write-null-mem.png differ diff --git a/doc/fig/write-null.png b/doc/fig/write-null.png new file mode 100644 index 0000000..4a1e53d Binary files /dev/null and b/doc/fig/write-null.png differ diff --git a/doc/fig/write.png b/doc/fig/write.png new file mode 100644 index 0000000..e095fe0 Binary files /dev/null and b/doc/fig/write.png differ diff --git a/tests/blocking-overhead.ae b/tests/blocking-overhead.ae index 1d5b033..32924d9 100644 --- a/tests/blocking-overhead.ae +++ b/tests/blocking-overhead.ae @@ -20,19 +20,40 @@ static double get_time () return (double) t.tv_sec + ((double) t.tv_usec / (1000000UL)); } -void regular_func (int a, void * b); +void regular_func_nomalloc_nomutex_noopa (int a, void * b) __attribute__ ((noinline)); +void regular_func_nomalloc_nomutex_noopa (int a, void * b) +{ + c = a + (intptr_t) b; +} + -void regular_func (int a, void * b) +void regular_func_malloc_nomutex_noopa (int a, void * b) __attribute__ ((noinline)); +void regular_func_malloc_nomutex_noopa (int a, void * b) { c = a + (intptr_t) b; - // OPA_cas_int (&a, 1, 2); + free (malloc (100)); +} + - // pthread_mutex_lock (&mutex); - //free (malloc (100)); - // pthread_mutex_unlock (&mutex); +void regular_func_malloc_mutex_noopa (int a, void * b) __attribute__ ((noinline)); +void regular_func_malloc_mutex_noopa (int a, void * b) +{ + c = a + (intptr_t) b; + pthread_mutex_lock (&mutex); + free (malloc (100)); + pthread_mutex_unlock (&mutex); } +void regular_func_malloc_nomutex_opa (int a, void * b) __attribute__ ((noinline)); +void regular_func_malloc_nomutex_opa (int a, void * b) +{ + c = a + (intptr_t) b; + OPA_int_t d; + OPA_cas_int (&d, 1, 2); + free (malloc (100)); +} + __blocking void blocking_func (int a, void * b); __blocking void blocking_func (int a, void * b) @@ -48,7 +69,6 @@ __blocking double do_blocking_test () start = get_time (); - printf ("Starting blocking test...\n"); for (i=0; i<CALL_COUNT; ++i) { blocking_func (count, 0); @@ -61,38 +81,49 @@ __blocking double do_blocking_test () } -double do_regular_test (void); - -double do_regular_test () -{ - unsigned long long count = 0; - unsigned long long i; - double start, stop; - printf ("Starting regular test...\n"); - - start = get_time (); - - for (i=0; i<CALL_COUNT; ++i) - { - regular_func (count, 0); - ++count; - } - - stop = get_time (); - return (stop-start); +#define CALL_REGULAR(a) \ +\ +double test_##a (void);\ +\ +double test_##a ()\ +{\ + unsigned long long count = 0;\ + unsigned long long i;\ + double start, stop;\ +\ + start = get_time ();\ +\ + for (i=0; i<CALL_COUNT; ++i)\ + {\ + a (count, 0);\ + ++count;\ + }\ +\ + stop = get_time ();\ + return (stop-start);\ } +CALL_REGULAR(regular_func_nomalloc_nomutex_noopa); +CALL_REGULAR(regular_func_malloc_nomutex_noopa ); +CALL_REGULAR(regular_func_malloc_mutex_noopa ); +CALL_REGULAR(regular_func_malloc_nomutex_opa ); + __blocking int aesop_main(int argc, char **argv) { double i; fprintf (stdout, "Making %lu calls.\n", CALL_COUNT); - i = do_regular_test (); - fprintf (stdout, "regular calls: %g (%g / call)\n", i, - i / CALL_COUNT); + + i = test_regular_func_nomalloc_nomutex_noopa (); + fprintf (stdout, "regular calls: %g (%g / call)\n", i, i / CALL_COUNT); + i = test_regular_func_malloc_nomutex_noopa (); + fprintf (stdout, "regular calls, malloc: %g (%g / call)\n", i, i / CALL_COUNT); + i = test_regular_func_malloc_mutex_noopa (); + fprintf (stdout, "regular calls, malloc, mutex: %g (%g / call)\n", i, i / CALL_COUNT); + i = test_regular_func_malloc_nomutex_opa (); + fprintf (stdout, "regular calls, malloc, opa: %g (%g / call)\n", i, i / CALL_COUNT); i = do_blocking_test (); - fprintf (stdout, "blocking calls: %g (%g / call)\n", i, - i / CALL_COUNT); + fprintf (stdout, "blocking calls: %g (%g / call)\n", i, i / CALL_COUNT); return 0; } hooks/post-receive -- aesop Repository

1 0

[aesop] #23: using nested scope variables are not supported and will fail silently
by aesop 22 Feb '12

22 Feb '12

#23: using nested scope variables are not supported and will fail silently ---------------------------+------------------------------------------------ Reporter: dkimpe | Owner: Type: defect | Status: new Priority: minor | Component: code generator Version: git repository | Keywords: ---------------------------+------------------------------------------------ The following aesop code will generate incorrect code: {{{ __blocking int test (int b) { int a; { double f; } } }}} Variables a and b are moved to the heap, but f is not. Note that the following does work as expected: {{{ { int f; blocking_call (); int a; blocking_call (); } }}} The code generator should at the very least detect these and issue an error. -- Ticket URL: <https://trac.mcs.anl.gov/projects/aesop/ticket/23> aesop <https://trac.mcs.anl.gov/projects/aesop> The Aesop Language

1 0

Wiki update: User:Gyanasr
by Wiki update: Asg-private: Carns 22 Feb '12

22 Feb '12

1 0