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 <[email protected]> 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