The aether Reference Manual

Table of Contents

The aether Reference Manual

This is the aether Reference Manual, version 1.0.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 14:00:42 2021 GMT+0.

1 Introduction

aether

aether is a Common Lisp framework for emulating an actor-based distributed system housed on a family of emulated devices.

Overview

The purpose of aether is to provide a testbed in which one can design the behaviors of distributed electronics, emulate software running on them, and instrument the emulation to infer software performance characteristics.

The framework is segmented into the following layers:

• Time-domain simulation via time-triggered events.
• Physical and logical network layers.
• An actor-based DSL.
• A library of standard patterns in distributed programming.

Each layer comes with standard instances which embody default behaviors. These can be used as-is for "macroscopic", detail-free emulation, and they can be subclassed to permit the injection of detailed, domain-specific behaviors (e.g., faithful emulation of network load). The actor-based DSL can be useful in the specification of both the behavior of the electronics and the behavior of the program: starting with the latter gives information about algorithm performance in the case of "ideal" hardware, and migrating to the latter pins down the performance features specific to that case.

Installation

The simplest installation method is to use Quicklisp: running (ql:quickload "aether") will download aether as well as any project dependencies.

Before aether is available via the Quicklisp index, or to use a bleeding-edge version, clone the aether git repository into your Quicklisp local project directory and then quickload as above.

Example

Here is an example description of a simple processor which responds to external impulses (i.e., messages on the aether network) to compute integer factorials.

(defclass arithmetic-server (process)
  ((process-clock-rate :initform 1))
  (:documentation "Simple server process that handles an arithmetic RPC call."))

;;; processor description / computational primitives

;; all PROCESS instances begin with the command START
(define-process-upkeep ((process arithmetic-server) now) (START)
  "Make the processor sit in an infinite \"listening\" loop."
  (process-continuation process `(START)))

(define-process-upkeep ((process arithmetic-server) now) (PUSH n)
  (push n (process-data-stack process)))

(define-process-upkeep ((process arithmetic-server) now) (MULTIPLY)
  (let ((left (pop (process-data-stack process)))
        (right (pop (process-data-stack process))))
    (push (* left right) (process-data-stack process))))

(define-process-upkeep ((process arithmetic-server) now) (EMIT address)
  (let* ((result (pop (process-data-stack process)))
         (message (make-message-rpc-done :result result)))
    (send-message address message)))

;;; public-facing factorial service

(defstruct (message-factorial (:include message))
  (n   nil :type (integer 0)))

(define-message-handler handle-message-factorial
    ((process arithmetic-server) (message message-factorial) now)
  (process-continuation process
                        `(FACTORIAL ,(message-factorial-n message))
                        `(EMIT ,(message-reply-channel message))))

(define-process-upkeep ((process arithmetic-server) now)
    (FACTORIAL n)
  (cond
    ((zerop n)
     (process-continuation process `(PUSH 1)))
    (t
     (process-continuation process
                           `(FACTORIAL ,(1- n))
                           `(PUSH ,n)
                           `(MULTIPLY)))))

;;; service registry

(define-message-dispatch arithmetic-server
  (message-factorial 'handle-message-factorial))

;;; example: spawning a server and querying it

;; set up the actors
(let* ((simulation (make-simulation))
       (*local-courier* (make-instance 'courier))
       (server (spawn-process 'arithmetic-server))
       (reply-channel (register)))
  (simulation-add-event simulation (make-event :callback server))
  (simulation-add-event simulation (make-event :callback *local-courier*))
  ;; send the factorial request
  (send-message (process-public-address server)
                (make-message-factorial :reply-channel reply-channel
                                        :n 15))
  ;; wait a while for it to complete
  (simulation-run simulation :canary (canary-until 60))
  ;; unpack the reply
  (receive-message (reply-channel done-message)
    (message-rpc-done
     (unregister reply-channel)
     (message-rpc-done-result done-message))))

Further examples can be found under the directory tests/examples/ in the source tree. They primarily demonstrate features of the standard library. These "living" examples are run regularly as part of the test suite.

License

aether is made available under the MIT license. See LICENSE.md in the source tree for more information.

See also

• ArXiv preprint
• GitHub repository

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 aether

Author

Eric Peterson <peterson.eric.c@gmail.com>

License

MIT (See LICENSE.md)

Description

A DSL for emulating an actor-based distributed system, housed on a family of emulated devices.

Version

1.0.1

Dependencies

• alexandria
• policy-cond
• cl-heap
• global-vars

Source

aether.asd (file)

Components

• package.lisp (file)
• utilities.lisp (file)
• queue.lisp (file)
• cheap-heap.lisp (file)
• debug (module)
• event.lisp (file)
• message.lisp (file)
• network.lisp (file)
• process (module)
• rpc.lisp (file)
• lock.lisp (file)
• cast.lisp (file)

3 Modules

Modules are listed depth-first from the system components tree.

3.1 aether/debug

Dependency

cheap-heap.lisp (file)

Parent

aether (system)

Location

debug/

Components

• logger.lisp (file)
• trace.lisp (file)

3.2 aether/process

Dependency

network.lisp (file)

Parent

aether (system)

Location

process/

Components

• process.lisp (file)
• dpu-helpers.lisp (file)
• dereference.lisp (file)
• emissary.lisp (file)

4 Files

Files are sorted by type and then listed depth-first from the systems components trees.

4.1 Lisp

4.1.1 aether.asd

Location

/home/quickref/quicklisp/dists/quicklisp/software/aether-v1.0.1/aether.asd

Systems

aether (system)

4.1.2 aether/package.lisp

Parent

aether (system)

Location

package.lisp

Packages

aether

4.1.3 aether/utilities.lisp

Dependency

package.lisp (file)

Parent

aether (system)

Location

utilities.lisp

Exported Definitions

• destructuring-places (macro)
• dohash (macro)
• ignorant-lambda (macro)
• initialize-and-return (macro)
• peek (function)

Internal Definitions

• assoc-default (macro)
• hash-let (macro)
• macro-lambda-list-places (function)

4.1.4 aether/queue.lisp

Dependency

utilities.lisp (file)

Parent

aether (system)

Location

queue.lisp

Exported Definitions

• make-q (function)
• q-deq (function)
• q-deq-first (function)
• q-deq-when (function)
• q-empty (function)
• q-enq (function)
• q-len (function)
• q-peek (function)
• q-push (function)

4.1.5 aether/cheap-heap.lisp

Dependency

queue.lisp (file)

Parent

aether (system)

Location

cheap-heap.lisp

Exported Definitions

• cheap-heap-dequeue (function)
• cheap-heap-enqueue (function)
• cheap-heap-peep (function)
• make-cheap-heap (function)

4.1.6 aether/debug/logger.lisp

Parent

debug (module)

Location

debug/logger.lisp

Exported Definitions

• *logger* (special variable)
• log-entry (function)
• logger-entries (function)
• (setf logger-entries) (function)
• print-log (function)
• print-message-report (function)
• reset-logger (function)
• with-transient-logger (macro)

Internal Definitions

• copy-logger (function)
• logger (structure)
• logger-p (function)
• make-logger (function)
• message-log (function)
• message-report (function)
• print-log-entry (generic function)
• print-log-entry (method)
• print-log-entry (method)

4.1.7 aether/debug/trace.lisp

Dependency

logger.lisp (file)

Parent

debug (module)

Location

debug/trace.lisp

Internal Definitions

• *message-traces* (special variable)
• copy-tracer (function)
• make-tracer (function)
• print-trace-table (function)
• print-traces (function)
• rotate-trace-table (function)
• sort-traces (function)
• tracer (structure)
• tracer-p (function)
• tracer-store (function)
• tracer-traces (function)
• (setf tracer-traces) (function)
• with-traces (macro)

4.1.8 aether/event.lisp

Dependency

debug (module)

Parent

aether (system)

Location

event.lisp

Exported Definitions

• canary-all (function)
• canary-any (function)
• canary-process (function)
• canary-timeout (function)
• canary-until (function)
• define-object-handler (macro)
• event (structure)
• finish-with-futures (function)
• future (function)
• future* (function)
• make-event (function)
• make-simulation (function)
• simulation (structure)
• simulation-add-event (function)
• simulation-run (function)
• with-futures (macro)
• with-simulation (macro)

Internal Definitions

• %make-simulation (function)
• copy-event (function)
• copy-simulation (function)
• event-callback (function)
• event-p (function)
• event-time (function)
• handle-object (generic function)
• simulation-contents (function)
• (setf simulation-contents) (function)
• simulation-dequeue (function)
• simulation-horizon (function)
• (setf simulation-horizon) (function)
• simulation-p (function)
• simulation-peep (function)

4.1.9 aether/message.lisp

Dependency

event.lisp (file)

Parent

aether (system)

Location

message.lisp

Exported Definitions

• *local-courier* (special variable)
• address (structure)
• address= (function)
• courier (structure)
• courier-processing-clock-rate (function)
• (setf courier-processing-clock-rate) (function)
• hash-address (function)
• make-courier (function)
• make-message (function)
• make-message-rpc-done (function)
• make-message-rts (function)
• message (structure)
• message-reply-channel (function)
• (setf message-reply-channel) (function)
• message-rpc-done (structure)
• message-rpc-done-result (function)
• (setf message-rpc-done-result) (function)
• message-rts (structure)
• receive-message (macro)
• register (function)
• send-message (function)
• send-message-batch (function)
• unregister (function)
• with-courier (macro)

Internal Definitions

• *courier-processing-clock-rate* (special variable)
• *routing-time-step* (special variable)
• address-channel (function)
• (setf address-channel) (function)
• address-courier (function)
• (setf address-courier) (function)
• address-p (function)
• address-secret (function)
• (setf address-secret) (function)
• check-key-secret (function)
• copy-address (function)
• copy-courier (function)
• copy-message (function)
• copy-message-rpc-done (function)
• copy-message-rts (function)
• courier-courier->route (generic function)
• courier-courier->route (method)
• courier-default-routing-time-step (function)
• (setf courier-default-routing-time-step) (function)
• courier-id (function)
• (setf courier-id) (function)
• courier-inboxes (function)
• (setf courier-inboxes) (function)
• courier-neighbors (function)
• (setf courier-neighbors) (function)
• courier-p (function)
• courier-queue (function)
• (setf courier-queue) (function)
• courier-secrets (function)
• (setf courier-secrets) (function)
• deliver-message (function)
• handle-object (method)
• make-address (function)
• message-message-id (function)
• (setf message-message-id) (function)
• message-p (function)
• message-rpc-done-message-id (function)
• (setf message-rpc-done-message-id) (function)
• message-rpc-done-p (function)
• message-rpc-done-reply-channel (function)
• (setf message-rpc-done-reply-channel) (function)
• message-rts-message-id (function)
• (setf message-rts-message-id) (function)
• message-rts-p (function)
• message-rts-reply-channel (function)
• (setf message-rts-reply-channel) (function)
• public-address (function)
• stash-local-message (function)

4.1.10 aether/network.lisp

Dependency

message.lisp (file)

Parent

aether (system)

Location

network.lisp

Exported Definitions

make-courier-grid (function)

Internal Definitions

• %make-courier-gridded (function)
• copy-courier-gridded (function)
• copy-grid-neighbors (function)
• courier-courier->route (method)
• courier-gridded (structure)
• courier-gridded-default-routing-time-step (function)
• (setf courier-gridded-default-routing-time-step) (function)
• courier-gridded-id (function)
• (setf courier-gridded-id) (function)
• courier-gridded-inboxes (function)
• (setf courier-gridded-inboxes) (function)
• courier-gridded-neighbors (function)
• (setf courier-gridded-neighbors) (function)
• courier-gridded-p (function)
• courier-gridded-processing-clock-rate (function)
• (setf courier-gridded-processing-clock-rate) (function)
• courier-gridded-queue (function)
• (setf courier-gridded-queue) (function)
• courier-gridded-secrets (function)
• (setf courier-gridded-secrets) (function)
• grid-neighbors (structure)
• grid-neighbors-down (function)
• (setf grid-neighbors-down) (function)
• grid-neighbors-left (function)
• (setf grid-neighbors-left) (function)
• grid-neighbors-p (function)
• grid-neighbors-right (function)
• (setf grid-neighbors-right) (function)
• grid-neighbors-up (function)
• (setf grid-neighbors-up) (function)
• make-courier-gridded (function)
• make-grid-neighbors (function)

4.1.11 aether/process/process.lisp

Parent

process (module)

Location

process/process.lisp

Exported Definitions

• define-message-dispatch (macro)
• define-message-handler (macro)
• define-process-upkeep (macro)
• process (class)
• process-clock-rate (method)
• (setf process-clock-rate) (method)
• process-command-stack (method)
• (setf process-command-stack) (method)
• process-continuation (function)
• process-data-stack (method)
• (setf process-data-stack) (method)
• process-debug? (method)
• (setf process-debug?) (method)
• process-exhaust-inbox? (method)
• (setf process-exhaust-inbox?) (method)
• process-peruse-inbox? (method)
• (setf process-peruse-inbox?) (method)
• process-public-address (function)

Internal Definitions

• %dpu-flet-definitions (function)
• %dpu-macrolet-definitions (function)
• define-dpu-flet (macro)
• define-dpu-macro (macro)
• handle-message-rts (method)
• handle-object (method)
• message-dispatch (generic function)
• process-courier (method)
• (setf process-courier) (method)
• process-key (method)
• (setf process-key) (method)
• process-upkeep (generic function)
• process-upkeep (method)

4.1.12 aether/process/dpu-helpers.lisp

Dependency

process.lisp (file)

Parent

process (module)

Location

process/dpu-helpers.lisp

Exported Definitions

• process-die (function)
• sync-receive (macro)
• with-replies (macro)

Internal Definitions

• %install-repeat-until (macro)
• process-upkeep (method)

4.1.13 aether/process/dereference.lisp

Dependency

dpu-helpers.lisp (file)

Parent

process (module)

Location

process/dereference.lisp

Exported Definitions

• dereference (function)
• spawn-process (function)
• with-address-dereferencing (macro)

Internal Definitions

• *dereferencing-table* (special variable)
• record-reference (function)

4.1.14 aether/process/emissary.lisp

Dependency

dereference.lisp (file)

Parent

process (module)

Location

process/emissary.lisp

Exported Definitions

define-message-subordinate (macro)

Internal Definitions

• message-dispatch (method)
• process-message-emissary (class)

4.1.15 aether/rpc.lisp

Dependency

process (module)

Parent

aether (system)

Location

rpc.lisp

Exported Definitions

• define-rpc-handler (macro)
• sync-rpc (macro)

4.1.16 aether/lock.lisp

Dependency

rpc.lisp (file)

Parent

aether (system)

Location

lock.lisp

Exported Definitions

• handle-message-lock (method)
• make-message-lock (function)
• make-message-unlock (function)
• message-lock (structure)
• process-lockable (class)
• process-lockable-aborting? (method)
• (setf process-lockable-aborting?) (method)
• process-lockable-done-signal (method)
• (setf process-lockable-done-signal) (method)
• process-lockable-locked? (method)
• (setf process-lockable-locked?) (method)
• process-lockable-targets (generic function)

Internal Definitions

• copy-message-lock (function)
• copy-message-unlock (function)
• message-lock-message-id (function)
• (setf message-lock-message-id) (function)
• message-lock-p (function)
• message-lock-reply-channel (function)
• (setf message-lock-reply-channel) (function)
• message-unlock (structure)
• message-unlock-message-id (function)
• (setf message-unlock-message-id) (function)
• message-unlock-p (function)
• message-unlock-reply-channel (function)
• (setf message-unlock-reply-channel) (function)
• message-unlock-result (function)
• (setf message-unlock-result) (function)
• process-upkeep (method)
• process-upkeep (method)
• process-upkeep (method)
• process-upkeep (method)
• process-upkeep (method)

4.1.17 aether/cast.lisp

Dependency

lock.lisp (file)

Parent

aether (system)

Location

cast.lisp

Exported Definitions

• broadcast-frame (structure)
• convergecast-frame (structure)
• define-broadcast-handler (macro)
• define-convergecast-handler (macro)
• make-broadcast-frame (function)
• make-convergecast-frame (function)
• push-broadcast-frame (function)
• push-convergecast-frame (function)
• return-from-cast (function)

Internal Definitions

• broadcast-frame-aborting? (function)
• (setf broadcast-frame-aborting?) (function)
• broadcast-frame-handle-rts? (function)
• (setf broadcast-frame-handle-rts?) (function)
• broadcast-frame-message (function)
• (setf broadcast-frame-message) (function)
• broadcast-frame-p (function)
• broadcast-frame-targets (function)
• (setf broadcast-frame-targets) (function)
• convergecast-frame-aborting? (function)
• (setf convergecast-frame-aborting?) (function)
• convergecast-frame-func (function)
• (setf convergecast-frame-func) (function)
• convergecast-frame-handle-rts? (function)
• (setf convergecast-frame-handle-rts?) (function)
• convergecast-frame-input (function)
• (setf convergecast-frame-input) (function)
• convergecast-frame-message (function)
• (setf convergecast-frame-message) (function)
• convergecast-frame-p (function)
• convergecast-frame-targets (function)
• (setf convergecast-frame-targets) (function)
• copy-broadcast-frame (function)
• copy-convergecast-frame (function)
• process-upkeep (method)
• process-upkeep (method)
• reduce+ (function)
• reduce-max (function)

5 Packages

Packages are listed by definition order.

5.1 aether

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions

• *local-courier* (special variable)
• *logger* (special variable)
• address (structure)
• address= (function)
• broadcast-frame (structure)
• canary-all (function)
• canary-any (function)
• canary-process (function)
• canary-timeout (function)
• canary-until (function)
• cheap-heap-dequeue (function)
• cheap-heap-enqueue (function)
• cheap-heap-peep (function)
• convergecast-frame (structure)
• courier (structure)
• courier-processing-clock-rate (function)
• (setf courier-processing-clock-rate) (function)
• define-broadcast-handler (macro)
• define-convergecast-handler (macro)
• define-message-dispatch (macro)
• define-message-handler (macro)
• define-message-subordinate (macro)
• define-object-handler (macro)
• define-process-upkeep (macro)
• define-rpc-handler (macro)
• dereference (function)
• destructuring-places (macro)
• dohash (macro)
• event (structure)
• finish-with-futures (function)
• future (function)
• future* (function)
• handle-message-lock (generic function)
• handle-message-lock (method)
• hash-address (function)
• ignorant-lambda (macro)
• initialize-and-return (macro)
• log-entry (function)
• logger-entries (function)
• (setf logger-entries) (function)
• make-broadcast-frame (function)
• make-cheap-heap (function)
• make-convergecast-frame (function)
• make-courier (function)
• make-courier-grid (function)
• make-event (function)
• make-message (function)
• make-message-lock (function)
• make-message-rpc-done (function)
• make-message-rts (function)
• make-message-unlock (function)
• make-q (function)
• make-simulation (function)
• message (structure)
• message-lock (structure)
• message-reply-channel (function)
• (setf message-reply-channel) (function)
• message-rpc-done (structure)
• message-rpc-done-result (function)
• (setf message-rpc-done-result) (function)
• message-rts (structure)
• peek (function)
• print-log (function)
• print-message-report (function)
• process (class)
• process-clock-rate (generic function)
• process-clock-rate (method)
• (setf process-clock-rate) (method)
• (setf process-clock-rate) (generic function)
• process-command-stack (generic function)
• process-command-stack (method)
• (setf process-command-stack) (method)
• (setf process-command-stack) (generic function)
• process-continuation (function)
• process-data-stack (generic function)
• process-data-stack (method)
• (setf process-data-stack) (method)
• (setf process-data-stack) (generic function)
• process-debug? (generic function)
• process-debug? (method)
• (setf process-debug?) (method)
• (setf process-debug?) (generic function)
• process-die (function)
• process-exhaust-inbox? (generic function)
• process-exhaust-inbox? (method)
• (setf process-exhaust-inbox?) (method)
• (setf process-exhaust-inbox?) (generic function)
• process-lockable (class)
• process-lockable-aborting? (generic function)
• process-lockable-aborting? (method)
• (setf process-lockable-aborting?) (method)
• (setf process-lockable-aborting?) (generic function)
• process-lockable-done-signal (generic function)
• process-lockable-done-signal (method)
• (setf process-lockable-done-signal) (method)
• (setf process-lockable-done-signal) (generic function)
• process-lockable-locked? (generic function)
• process-lockable-locked? (method)
• (setf process-lockable-locked?) (method)
• (setf process-lockable-locked?) (generic function)
• process-lockable-targets (generic function)
• process-peruse-inbox? (generic function)
• process-peruse-inbox? (method)
• (setf process-peruse-inbox?) (method)
• (setf process-peruse-inbox?) (generic function)
• process-public-address (function)
• push-broadcast-frame (function)
• push-convergecast-frame (function)
• q-deq (function)
• q-deq-first (function)
• q-deq-when (function)
• q-empty (function)
• q-enq (function)
• q-len (function)
• q-peek (function)
• q-push (function)
• receive-message (macro)
• register (function)
• reset-logger (function)
• return-from-cast (function)
• send-message (function)
• send-message-batch (function)
• simulation (structure)
• simulation-add-event (function)
• simulation-run (function)
• spawn-process (function)
• sync-receive (macro)
• sync-rpc (macro)
• unregister (function)
• with-address-dereferencing (macro)
• with-courier (macro)
• with-futures (macro)
• with-replies (macro)
• with-simulation (macro)
• with-transient-logger (macro)

Internal Definitions

• %dpu-flet-definitions (function)
• %dpu-macrolet-definitions (function)
• %install-repeat-until (macro)
• %make-courier-gridded (function)
• %make-simulation (function)
• *courier-processing-clock-rate* (special variable)
• *dereferencing-table* (special variable)
• *message-traces* (special variable)
• *routing-time-step* (special variable)
• address-channel (function)
• (setf address-channel) (function)
• address-courier (function)
• (setf address-courier) (function)
• address-p (function)
• address-secret (function)
• (setf address-secret) (function)
• assoc-default (macro)
• broadcast-frame-aborting? (function)
• (setf broadcast-frame-aborting?) (function)
• broadcast-frame-handle-rts? (function)
• (setf broadcast-frame-handle-rts?) (function)
• broadcast-frame-message (function)
• (setf broadcast-frame-message) (function)
• broadcast-frame-p (function)
• broadcast-frame-targets (function)
• (setf broadcast-frame-targets) (function)
• check-key-secret (function)
• convergecast-frame-aborting? (function)
• (setf convergecast-frame-aborting?) (function)
• convergecast-frame-func (function)
• (setf convergecast-frame-func) (function)
• convergecast-frame-handle-rts? (function)
• (setf convergecast-frame-handle-rts?) (function)
• convergecast-frame-input (function)
• (setf convergecast-frame-input) (function)
• convergecast-frame-message (function)
• (setf convergecast-frame-message) (function)
• convergecast-frame-p (function)
• convergecast-frame-targets (function)
• (setf convergecast-frame-targets) (function)
• copy-address (function)
• copy-broadcast-frame (function)
• copy-convergecast-frame (function)
• copy-courier (function)
• copy-courier-gridded (function)
• copy-event (function)
• copy-grid-neighbors (function)
• copy-logger (function)
• copy-message (function)
• copy-message-lock (function)
• copy-message-rpc-done (function)
• copy-message-rts (function)
• copy-message-unlock (function)
• copy-simulation (function)
• copy-tracer (function)
• courier-courier->route (generic function)
• courier-courier->route (method)
• courier-courier->route (method)
• courier-default-routing-time-step (function)
• (setf courier-default-routing-time-step) (function)
• courier-gridded (structure)
• courier-gridded-default-routing-time-step (function)
• (setf courier-gridded-default-routing-time-step) (function)
• courier-gridded-id (function)
• (setf courier-gridded-id) (function)
• courier-gridded-inboxes (function)
• (setf courier-gridded-inboxes) (function)
• courier-gridded-neighbors (function)
• (setf courier-gridded-neighbors) (function)
• courier-gridded-p (function)
• courier-gridded-processing-clock-rate (function)
• (setf courier-gridded-processing-clock-rate) (function)
• courier-gridded-queue (function)
• (setf courier-gridded-queue) (function)
• courier-gridded-secrets (function)
• (setf courier-gridded-secrets) (function)
• courier-id (function)
• (setf courier-id) (function)
• courier-inboxes (function)
• (setf courier-inboxes) (function)
• courier-neighbors (function)
• (setf courier-neighbors) (function)
• courier-p (function)
• courier-queue (function)
• (setf courier-queue) (function)
• courier-secrets (function)
• (setf courier-secrets) (function)
• define-dpu-flet (macro)
• define-dpu-macro (macro)
• deliver-message (function)
• event-callback (function)
• event-p (function)
• event-time (function)
• grid-neighbors (structure)
• grid-neighbors-down (function)
• (setf grid-neighbors-down) (function)
• grid-neighbors-left (function)
• (setf grid-neighbors-left) (function)
• grid-neighbors-p (function)
• grid-neighbors-right (function)
• (setf grid-neighbors-right) (function)
• grid-neighbors-up (function)
• (setf grid-neighbors-up) (function)
• handle-message-rts (generic function)
• handle-message-rts (method)
• handle-object (generic function)
• handle-object (method)
• handle-object (method)
• hash-let (macro)
• logger (structure)
• logger-p (function)
• macro-lambda-list-places (function)
• make-address (function)
• make-courier-gridded (function)
• make-grid-neighbors (function)
• make-logger (function)
• make-tracer (function)
• message-dispatch (generic function)
• message-dispatch (method)
• message-lock-message-id (function)
• (setf message-lock-message-id) (function)
• message-lock-p (function)
• message-lock-reply-channel (function)
• (setf message-lock-reply-channel) (function)
• message-log (function)
• message-message-id (function)
• (setf message-message-id) (function)
• message-p (function)
• message-report (function)
• message-rpc-done-message-id (function)
• (setf message-rpc-done-message-id) (function)
• message-rpc-done-p (function)
• message-rpc-done-reply-channel (function)
• (setf message-rpc-done-reply-channel) (function)
• message-rts-message-id (function)
• (setf message-rts-message-id) (function)
• message-rts-p (function)
• message-rts-reply-channel (function)
• (setf message-rts-reply-channel) (function)
• message-unlock (structure)
• message-unlock-message-id (function)
• (setf message-unlock-message-id) (function)
• message-unlock-p (function)
• message-unlock-reply-channel (function)
• (setf message-unlock-reply-channel) (function)
• message-unlock-result (function)
• (setf message-unlock-result) (function)
• print-log-entry (generic function)
• print-log-entry (method)
• print-log-entry (method)
• print-trace-table (function)
• print-traces (function)
• process-courier (generic function)
• process-courier (method)
• (setf process-courier) (method)
• (setf process-courier) (generic function)
• process-key (generic function)
• process-key (method)
• (setf process-key) (method)
• (setf process-key) (generic function)
• process-message-emissary (class)
• process-upkeep (generic function)
• process-upkeep (method)
• process-upkeep (method)
• process-upkeep (method)
• process-upkeep (method)
• process-upkeep (method)
• process-upkeep (method)
• process-upkeep (method)
• process-upkeep (method)
• process-upkeep (method)
• public-address (function)
• record-reference (function)
• reduce+ (function)
• reduce-max (function)
• rotate-trace-table (function)
• simulation-contents (function)
• (setf simulation-contents) (function)
• simulation-dequeue (function)
• simulation-horizon (function)
• (setf simulation-horizon) (function)
• simulation-p (function)
• simulation-peep (function)
• sort-traces (function)
• stash-local-message (function)
• tracer (structure)
• tracer-p (function)
• tracer-store (function)
• tracer-traces (function)
• (setf tracer-traces) (function)
• with-traces (macro)

6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

6.1 Exported definitions

6.1.1 Special variables

Special Variable: *local-courier*

Bound to the ‘COURIER’ that services this process.

Package

aether

Source

message.lisp (file)

Special Variable: *logger*

Package

aether

Source

logger.lisp (file)

6.1.2 Macros

Macro: define-broadcast-handler HANDLER-NAME ((PROCESS PROCESS-TYPE) (MESSAGE MESSAGE-TYPE) NOW) &body BODY

This macro augments ‘DEFINE-MESSAGE-HANDLER’, by pushing a ‘BROADCAST’ command onto the ‘PROCESS’s command stack. This command takes no arguments, but expects a ‘BROADCAST-FRAME’ to be on the data stack when it is called. Thus, either the handler must prepare the data frame, or it must be prepared by whatever script is pushed onto the command stack by the handler. Additionally, inside the context of ‘DEFINE-BROADCAST-HANDLER’ we have access to a pair of helper functions:

1. ‘PUSH-BROADCAST-FRAME’, which creates a ‘BROADCAST-FRAME’ and pushes it onto the data stack. If no ‘MESSAGE’ is provided to the function, it defaults to the ‘MESSAGE’ currently being handled. If a user calls ‘PUSH-BROADCAST-FRAME’ twice in the same handler, an error will be raised.
2. ‘RETURN-FROM-CAST’, which allows the user to terminate the broadcast operation early by sending up an acknowledgement (optionally specifying its contents) to the original sender of ‘MESSAGE’.

WARNING: ‘RETURN-FROM-CAST’ calls ‘PUSH-BROADCAST-FRAME’ as part of the aborting process. If a frame has already been pushed onto the data stack, we instead alter that frame rather than pushing an additional one (which could have strange consequences). Additionally, it is important to note that ‘RETURN-FROM-CAST’ uses ‘FINISH-WITH-FUTURES’ in order to return from the handler early.

Package

aether

Source

cast.lisp (file)

Macro: define-convergecast-handler HANDLER-NAME ((PROCESS PROCESS-TYPE) (MESSAGE MESSAGE-TYPE) NOW) &body BODY

This macro augments ‘DEFINE-MESSAGE-HANDLER’, by pushing a ‘CONVERGECAST’ command onto the ‘PROCESS’s command stack. This command takes no arguments, but expects a ‘CONVERGECAST-FRAME’ to be on the data stack when it is called. Thus, either the handler must prepare the data frame, or it must be prepared by whatever script is pushed onto the command stack by the handler. Additionally, inside the context of ‘DEFINE-CONVERGECAST-HANDLER’ we have access to a pair of helper functions:

1. ‘PUSH-CONVERGECAST-FRAME’, which creates a ‘CONVERGECAST-FRAME’ and pushes it onto the data stack. If no ‘MESSAGE’ is provided to the function, it defaults to the ‘MESSAGE’ currently being handled. If a user calls ‘PUSH-BROADCAST-FRAME’ twice in the same handler, an error will be raised.
2. ‘RETURN-FROM-CAST’, which allows the user to terminate the convergecast operation early by sending up an acknowledgement (optionally specifying its contents) to the original sender of ‘MESSAGE’. It is recommended that a value is provided when returning from a convergecast, as it will be passed to a function (the function provided to the ‘CONVERGECAST-FRAME’) when received by the original sender.

WARNING: ‘RETURN-FROM-CAST’ calls ‘PUSH-CONVERGECAST-FRAME’ as part of the aborting process. If a frame has already been pushed onto the data stack, we instead alter that frame rather than pushing an additional one (which could have strange consequences). Additionally, it is important to note that ‘RETURN-FROM-CAST’ uses ‘FINISH-WITH-FUTURES’ in order to return from the handler early.

Package

aether

Source

cast.lisp (file)

Macro: define-message-dispatch NODE-TYPE &body CLAUSES

Defines "automatic" message handlers associated to a particular subtype of ‘PROCESS’. Each handler is specified by a tuple of form (MESSAGE-TYPE MESSAGE-HANDLER &OPTIONAL GUARD). As with ‘RECEIVE-MESSAGE’, each clause is processed in turn, according to the following rules:

+ If supplied, ‘GUARD’ is evaluated with the ‘PROCESS’ in question bound to the place ‘PROCESS-TYPE’. If ‘GUARD’ evaluates to NIL, proceed to the next clause.
+ Check the message queue at the public address for an item of type ‘MESSAGE-TYPE’. If such a message is found, call the associated ‘MESSAGE-HANDLER’ with lambda triple (PROCESS MESSAGE TIME). Otherwise, proceed to the next clause.

NOTES:
+ If no clause is matched, execution proceeds to the semantics specified by ‘DEFINE-PROCESS-UPKEEP’.
+ Automatically appends a ‘MESSAGE-RTS’ clause which calls ‘HANDLE-MESSAGE-RTS’ and results in an error. Because of this, we set ‘CATCH-RTS?’ to NIL when processing clauses and building ‘RECEIVE-MESSAGE’ blocks. Otherwise, it would be impossible to override the default handling of ‘MESSAGE-RTS’es. + ‘PROCESS-PERUSE-INBOX?’ is passed along to ‘RECEIVE-MESSAGE’, where it determines how we search for a message to handle.

WARNING: These actions are to be thought of as "interrupts". Accordingly, you will probably stall the underlying ‘PROCESS’ if you perform some waiting action here, like the analogue of a ‘SYNC-RECEIVE’.

Package

aether

Source

process.lisp (file)

Macro: define-message-handler HANDLER-NAME ((PROCESS PROCESS-TYPE) (MESSAGE MESSAGE-TYPE) TIME) &body BODY

Defines a function to be invoked by DEFINE-MESSAGE-DISPATCH.

Package

aether

Source

process.lisp (file)

Macro: define-message-subordinate HANDLER-NAME ((PROCESS PROCESS-TYPE) (MESSAGE MESSAGE-TYPE) NOW) &body BODY

Interrupt-based RPC handlers are expected to emit a reply to the caller. This macro augments DEFINE-MESSAGE-HANDLER to reply to the caller with the last evaluated form.

Package

aether

Source

emissary.lisp (file)

Macro: define-object-handler ((OBJECT-VARIABLE OBJECT-TYPE) TIME-VARIABLE) &body BODY

Defines a default event handler for OBJECT-TYPE.

Package

aether

Source

event.lisp (file)

Macro: define-process-upkeep ((PROCESS-NAME PROCESS-TYPE) NOW) (COMMAND &rest COMMAND-ARGS) &body BODY

Defines the behavior of a particular PROCESS (of type PROCESS-TYPE) as it enacts a COMMAND.

PROCESS is COMMAND is a KEYWORD, and COMMAND-ARGS is a DESTRUCTURING-BIND-LAMBDA-LIST.

Locally enables the use of the function PROCESS-DIE and the special form SYNC-RECEIVE.

Package

aether

Source

process.lisp (file)

Macro: define-rpc-handler HANDLER-NAME ((PROCESS PROCESS-TYPE) (MESSAGE MESSAGE-TYPE) NOW) &body BODY

Interrupt-based RPC handlers are expected to emit a reply to the caller. This macro augments DEFINE-MESSAGE-HANDLER to reply to the caller with the last evaluated form.

Package

aether

Source

rpc.lisp (file)

Macro: destructuring-places LAMBDA-LIST EXPRESSION &body BODY

A variant of DESTRUCTURING-BIND that provides SETFs in the style of WITH-SLOTS, but it can only handle the required part of a DESTRUCTURING-LAMBDA-LIST.

Package

aether

Source

utilities.lisp (file)

Macro: dohash ((KEY VALUE) HASH-TABLE &optional RETURN-FORM) &body BODY

Iterates over HASH-TABLE, defining a lexical binding KEY and a place VALUE for each iteration of BODY. Optionally evaluates RETURN-FORM at termination and returns its result; otherwise returns NIL.

WARNING: This routine is based on MAPHASH, which has undefined behavior if the structure of HASH-TABLE is modified during iteration (e.g., the addition of new entries, or the modification of any entry not currently being processed).

Package

aether

Source

utilities.lisp (file)

Macro: ignorant-lambda &body BODY

Defines an anonymous function that discards all of its arguments.

Package

aether

Source

utilities.lisp (file)

Macro: initialize-and-return (&rest BINDINGS) &body BODY

Returns (in reverse order, as VALUES) the contents of BINDINGS after the evaluation of BODY.

Package

aether

Source

utilities.lisp (file)

Macro: receive-message (ADDRESS MESSAGE &key TIMEOUT CATCH-RTS? PERUSE-INBOX? &allow-other-keys) &body CLAUSES

Peruses the mailbox at ‘ADDRESS’ for a ‘MESSAGE’ which matches one of the provided ‘CLAUSES’. Each clause has the form (MESSAGE-TYPE &BODY BODY). Clauses are processed according to the following Erlang-ian rules:

+ Each clause is processed in the order supplied.
+ If a clause is matched, no further clauses are processed.
+ When ‘PERUSE-INBOX?’ is T, each clause (processed in order) searches the whole inbox(in latest-to-most-recent order) for a ‘MESSAGE-TYPE’ match. When NIL, each clause just looks at the first message in the inbox for a ‘MESSAGE-TYPE’ match. + If a waiting message of the appropriate type is found, it is bound to ‘MESSAGE’ and ‘BODY’ is processed.

NOTES:

When ‘CATCH-RTS?’ is T, we append a ‘MESSAGE-RTS’ clause that throws an error.

Permits a clause with head ‘OTHERWISE’ which is executed when no such waiting message is found.

Returns as a secondary value whether a message was processed. (An ‘OTHERWISE’ clause also results in a secondary value of NIL.)

Package

aether

Source

message.lisp (file)

Macro: sync-receive (SYNC-CHANNEL SYNC-MESSAGE-PLACE) &body SYNC-CLAUSES

Models a blocking ‘RECEIVE-MESSAGE’ command.

IMPORTANT WARNING: ‘SYNC-RECEIVE’ returns after it finishes executing its body. Any code following a ‘SYNC-RECEIVE’ **will not** be executed.

NOTE: ‘MESSAGE-RTS’ replies must be explicitly handled. Otherwise, the default behavior is to throw an error, which can be seen in the definition of ‘RECEIVE-MESSAGE’.

NOTE: SYNC-RECEIVE is not available outside the body of DEFINE-PROCESS-UPKEEP.

Package

aether

Source

dpu-helpers.lisp (file)

Macro: sync-rpc MESSAGE (RESULT-PLACE-OR-LIST DESTINATION &key RETURNED?) &body BODY

Performs a synchronized RPC call. Only allowed inside the body of DEFINE-PROCESS-UPKEEP.

Sends ‘MESSAGE’ to ‘DESTINATION’, waits for a reply, and unpacks the reply into ‘RESULT-PLACE-OR-LIST’.

If ‘RETURNED?’ is supplied and this call generates a ‘MESSAGE-RTS’ reply, then ‘RETURNED?’ will be flagged and control resumes. Otherwise, controlled is interrupted by an error.

Package

aether

Source

rpc.lisp (file)

Macro: with-address-dereferencing () &body BODY

Context macro which permits use of DEREFERENCE in its body.

Package

aether

Source

dereference.lisp (file)

Macro: with-courier (&rest KEYWORD-ARGUMENTS) &body BODY

Initializes the ‘*LOCAL-COURIER*’ parameter as a fresh ‘COURIER’. Also takes a list of ‘KEYWORD-ARGUMENT’s (e.g. :processing-clock-rate 20) that are passed along to the constructor.

Package

aether

Source

message.lisp (file)

Macro: with-futures &body BODY

Stores an implicit set of EVENT objects to return when exiting the WITH-FUTURE block.

Provides some helper functions: FUTURE, FUTURE*, and FINISH-WITH-FUTURES.

Package

aether

Source

event.lisp (file)

Macro: with-replies (REPLIES &key RETURNED? CLOSE? MESSAGE-TYPE MESSAGE-UNPACKER) ADDRESSES &body BODY

Amasses results from ‘MESSAGE-RPC-DONE’ messages received on ‘ADDRESSES’ into a list stored in ‘REPLIES’. This list is sorted in the same order as ‘ADDRESSES’. Execution of ‘BODY’ resumes when each address has received such a message.

If ‘RETURNED?’ is supplied, then in the event of a ‘MESSAGE-RTS’, this flag is set. If it is not supplied, this raises an error.

Typical use looks like:

(with-replies
(replies :returned? returned?)
(send-message-batch #’make-blossom-msg-scan targets)
(let ((reply (reduce #’unify-pongs replies)))
(send-message reply-channel reply)))

NOTE: WITH-REPLIES is not available outside the body of DEFINE-PROCESS-UPKEEP.

Package

aether

Source

dpu-helpers.lisp (file)

Macro: with-simulation (NAME (&rest STARTING-OBJECTS)) &body BODY

Initializes a new SIMULATION bound to name NAME using MAKE-SIMULATION and adds an EVENT to the SIMULATION at time 0 for every object in STARTING-OBJECTs.

Package

aether

Source

event.lisp (file)

Macro: with-transient-logger () &body BODY

Initialize a fresh logger. Returns log contents on close.

Package

aether

Source

logger.lisp (file)

6.1.3 Functions

Function: address= LEFT RIGHT

Tests for semantic equality of addresses.

Package

aether

Source

message.lisp (file)

Function: canary-all &rest CANARIES

Announce a trigger when all of the CANARIES are simultaneously triggered.

Package

aether

Source

event.lisp (file)

Function: canary-any &rest CANARIES

Announce a trigger when any one of the CANARIES is triggered.

Package

aether

Source

event.lisp (file)

Function: canary-process PROCESS

Pause a simulation when PROCESS halts.

Package

aether

Source

event.lisp (file)

Function: canary-timeout TIMEOUT

Throw an error when TIMEOUT arrives.

Package

aether

Source

event.lisp (file)

Function: canary-until UNTIL

Pause a simulation after UNTIL passes.

Package

aether

Source

event.lisp (file)

Function: cheap-heap-dequeue HEAP

Package

aether

Source

cheap-heap.lisp (file)

Function: cheap-heap-enqueue HEAP ITEM KEY

Package

aether

Source

cheap-heap.lisp (file)

Function: cheap-heap-peep HEAP

Package

aether

Source

cheap-heap.lisp (file)

Function: courier-processing-clock-rate INSTANCE

Function: (setf courier-processing-clock-rate) VALUE INSTANCE

Package

aether

Source

message.lisp (file)

Function: dereference ADDRESS

Looks up the Lisp PROCESS object which owns the provided public ADDRESS. Only functions within WITH-ADDRESS-DEREFERENCING, not hardware-realistic, only for use during debugging.

Package

aether

Source

dereference.lisp (file)

Function: finish-with-futures &optional EVENT-LIST

Breaks out of WITH-FUTURE. If EVENTS is supplied, returns EVENTS in place of the implicit event list.

Package

aether

Source

event.lisp (file)

Function: future FN-OR-OBJ TIME

Installs a future EVENT object, which invokes FN-OR-OBJ at the specified TIME.

Package

aether

Source

event.lisp (file)

Function: future* EVENT-LIST

Installs a list of future EVENT objects.

Package

aether

Source

event.lisp (file)

Function: hash-address ADDRESS

Package

aether

Source

message.lisp (file)

Function: log-entry &rest INITARGS &key LOGGER SOURCE SOURCE-TYPE TIME ENTRY-TYPE &allow-other-keys

Injects a log entry.

Package

aether

Source

logger.lisp (file)

Function: logger-entries INSTANCE

Function: (setf logger-entries) VALUE INSTANCE

Package

aether

Source

logger.lisp (file)

Function: make-broadcast-frame &key (ABORTING? ABORTING?) (HANDLE-RTS? HANDLE-RTS?) (MESSAGE MESSAGE) (TARGETS TARGETS)

Package

aether

Source

cast.lisp (file)

Function: make-cheap-heap ()

Package

aether

Source

cheap-heap.lisp (file)

Function: make-convergecast-frame &key (ABORTING? ABORTING?) (HANDLE-RTS? HANDLE-RTS?) (MESSAGE MESSAGE) (TARGETS TARGETS) (FUNC FUNC) (INPUT INPUT)

Package

aether

Source

cast.lisp (file)

Function: make-courier &key (QUEUE QUEUE) (INBOXES INBOXES) (SECRETS SECRETS) (PROCESSING-CLOCK-RATE PROCESSING-CLOCK-RATE) (DEFAULT-ROUTING-TIME-STEP DEFAULT-ROUTING-TIME-STEP) (ID ID) (NEIGHBORS NEIGHBORS)

Package

aether

Source

message.lisp (file)

Function: make-courier-grid SIZE-I SIZE-J

Constructs a (size-i x size-j) grid of COURIER-GRIDDED instances.

Package

aether

Source

network.lisp (file)

Function: make-event &key (CALLBACK CALLBACK) (TIME TIME)

Package

aether

Source

event.lisp (file)

Function: make-message &key (REPLY-CHANNEL REPLY-CHANNEL) (MESSAGE-ID MESSAGE-ID)

Package

aether

Source

message.lisp (file)

Function: make-message-lock &key (REPLY-CHANNEL REPLY-CHANNEL) (MESSAGE-ID MESSAGE-ID)

Package

aether

Source

lock.lisp (file)

Function: make-message-rpc-done &key (REPLY-CHANNEL REPLY-CHANNEL) (MESSAGE-ID MESSAGE-ID) (RESULT RESULT)

Package

aether

Source

message.lisp (file)

Function: make-message-rts &key (REPLY-CHANNEL REPLY-CHANNEL) (MESSAGE-ID MESSAGE-ID)

Package

aether

Source

message.lisp (file)

Function: make-message-unlock &key (REPLY-CHANNEL REPLY-CHANNEL) (MESSAGE-ID MESSAGE-ID) (RESULT RESULT)

Package

aether

Source

lock.lisp (file)

Function: make-q &rest ITEMS

Package

aether

Source

queue.lisp (file)

Function: make-simulation ()

Constructs an empty SIMULATION.

Package

aether

Source

event.lisp (file)

Function: message-reply-channel INSTANCE

Function: (setf message-reply-channel) VALUE INSTANCE

Package

aether

Source

message.lisp (file)

Function: message-rpc-done-result INSTANCE

Function: (setf message-rpc-done-result) VALUE INSTANCE

Package

aether

Source

message.lisp (file)

Function: peek LIST

Synonym for the PEEK operation on a stack.

Package

aether

Source

utilities.lisp (file)

Function: print-log ENTRIES &optional STREAM

Package

aether

Source

logger.lisp (file)

Function: print-message-report &optional LOGGER

Print a report of the different types of messages sent in ‘LOGGER’, and a count for each. Calls ‘MESSAGE-LOG’ and ‘MESSAGE-REPORT’.

Package

aether

Source

logger.lisp (file)

Function: process-continuation PROCESS &rest COMMANDS

Installs ‘COMMANDS’ to be executed as next steps by ‘PROCESS’.

Package

aether

Source

process.lisp (file)

Function: process-die ()

PROCESS-DIE causes the current PROCESS to release its public mailbox and exit the parent SIMULATION loop.

NOTE: PROCESS-DIE is not available outside the body of DEFINE-PROCESS-UPKEEP.

Package

aether

Source

dpu-helpers.lisp (file)

Function: process-public-address PROCESS

Extracts the public ADDRESS associated to PROCESS.

Package

aether

Source

process.lisp (file)

Function: push-broadcast-frame &key ABORTING? HANDLE-RTS? MESSAGE TARGETS

Convenience function for creating a ‘BROADCAST-FRAME’ and pushing it onto the ‘PROCESS-DATA-STACK’.

Package

aether

Source

cast.lisp (file)

Function: push-convergecast-frame &key ABORTING? HANDLE-RTS? FUNC INPUT MESSAGE TARGETS

Convenience function for creating a ‘CONVERGECAST-FRAME’ and pushing it onto the ‘PROCESS-DATA-STACK’.

Package

aether

Source

cast.lisp (file)

Function: q-deq Q

Package

aether

Source

queue.lisp (file)

Function: q-deq-first Q PRED

Dequeue the first message in ‘Q’ that satisfies ‘PRED’.

Package

aether

Source

queue.lisp (file)

Function: q-deq-when Q PRED

Dequeue the message at the front of ‘Q’ when ‘PRED’ is T.

Package

aether

Source

queue.lisp (file)

Function: q-empty Q

Package

aether

Source

queue.lisp (file)

Function: q-enq EL Q

Package

aether

Source

queue.lisp (file)

Function: q-len Q

Package

aether

Source

queue.lisp (file)

Function: q-peek Q

Package

aether

Source

queue.lisp (file)

Function: q-push Q EL

Package

aether

Source

queue.lisp (file)

Function: register &key COURIER CHANNEL SECRET

Registers a fresh channel over which messages can be transmitted and received.

Package

aether

Source

message.lisp (file)

Function: reset-logger &optional LOGGER

Empties the current logger of all entries.

Package

aether

Source

logger.lisp (file)

Function: return-from-cast &optional VALUE REASON

Allows the user to return early from a broadcast or convergecast operation.

Package

aether

Source

cast.lisp (file)

Function: send-message DESTINATION PAYLOAD

Sends the message ‘PAYLOAD’ to be received at ‘DESTINATION’, an ‘ADDRESS’. Returns the ‘REPLY-CHANNEL’ of the ‘PAYLOAD’, if any.

Package

aether

Source

message.lisp (file)

Function: send-message-batch PAYLOAD-CONSTRUCTOR DESTINATIONS &key REPLIES?

Sends a batch of messages to the ‘ADDRESS’es housed in ‘DESTINATIONS’. Each message is constructed afresh using ‘PAYLOAD-CONSTRUCTOR’, supplied with a freshly registered reply channel, and the list of reply channels is returned as a result.

Package

aether

Source

message.lisp (file)

Function: simulation-add-event SIMULATION EVENT

Installs EVENT into SIMULATION for later processing.

Package

aether

Source

event.lisp (file)

Function: simulation-run SIMULATION &key CANARY

Processes EVENTs belonging to SIMULATION, until either SIMULATION is exhausted or CANARY evaluates to T.

Package

aether

Source

event.lisp (file)

Function: spawn-process CLASS &rest INITARGS

Preferred mechanism for instantiating an object inherting from PROCESS. Contains debug hooks.

Package

aether

Source

dereference.lisp (file)

Function: unregister ADDRESS

Unregisters a channel, so that messages can no longer be transmitted or received over it.

Package

aether

Source

message.lisp (file)

6.1.4 Generic functions

Generic Function: handle-message-lock PROCESS MESSAGE NOW

Package

aether

Methods

Method: handle-message-lock (PROCESS process-lockable) (MESSAGE message-lock) NOW

Attempts to lock PROCESS.

Source

lock.lisp (file)

Generic Function: process-clock-rate OBJECT

Generic Function: (setf process-clock-rate) NEW-VALUE OBJECT

Package

aether

Methods

Method: process-clock-rate (PROCESS process)

Method: (setf process-clock-rate) NEW-VALUE (PROCESS process)

The number of times per unit of ‘SIMULATION’ time that this ‘PROCESS’ gets to act.

Source

process.lisp (file)

Generic Function: process-command-stack OBJECT

Generic Function: (setf process-command-stack) NEW-VALUE OBJECT

Package

aether

Methods

Method: process-command-stack (PROCESS process)

Method: (setf process-command-stack) NEW-VALUE (PROCESS process)

A stack populated with the instructions yet to be executed by this PROCESS. Modify this using ‘PROCESS-CONTINUATION’.

Source

process.lisp (file)

Generic Function: process-data-stack OBJECT

Generic Function: (setf process-data-stack) NEW-VALUE OBJECT

Package

aether

Methods

Method: process-data-stack (PROCESS process)

Method: (setf process-data-stack) NEW-VALUE (PROCESS process)

A stack populated with data, typically "data frames" pushed and popped by sequences of related commands.

Source

process.lisp (file)

Generic Function: process-debug? OBJECT

Generic Function: (setf process-debug?) NEW-VALUE OBJECT

Package

aether

Methods

Method: process-debug? (PROCESS process)

Method: (setf process-debug?) NEW-VALUE (PROCESS process)

A boolean flag. If T, debug messages are logged.

Source

process.lisp (file)

Generic Function: process-exhaust-inbox? OBJECT

Generic Function: (setf process-exhaust-inbox?) NEW-VALUE OBJECT

Package

aether

Methods

Method: process-exhaust-inbox? (PROCESS process)

Method: (setf process-exhaust-inbox?) NEW-VALUE (PROCESS process)

Defaults to T, which means that the ‘PROCESS’ will go through its entire message queue in a single clock tick, and then (in the same tick) take an action specified by the command stack. Otherwise, the ‘PROCESS’ will immediately execute a command after handling either zero or one message(s).

Source

process.lisp (file)

Generic Function: process-lockable-aborting? OBJECT

Generic Function: (setf process-lockable-aborting?) NEW-VALUE OBJECT

Package

aether

Methods

Method: process-lockable-aborting? (PROCESS-LOCKABLE process-lockable)

automatically generated reader method

Source

lock.lisp (file)

Method: (setf process-lockable-aborting?) NEW-VALUE (PROCESS-LOCKABLE process-lockable)

automatically generated writer method

Source

lock.lisp (file)

Generic Function: process-lockable-done-signal OBJECT

Generic Function: (setf process-lockable-done-signal) NEW-VALUE OBJECT

Package

aether

Methods

Method: process-lockable-done-signal (PROCESS-LOCKABLE process-lockable)

automatically generated reader method

Source

lock.lisp (file)

Method: (setf process-lockable-done-signal) NEW-VALUE (PROCESS-LOCKABLE process-lockable)

automatically generated writer method

Source

lock.lisp (file)

Generic Function: process-lockable-locked? OBJECT

Generic Function: (setf process-lockable-locked?) NEW-VALUE OBJECT

Package

aether

Methods

Method: process-lockable-locked? (PROCESS-LOCKABLE process-lockable)

automatically generated reader method

Source

lock.lisp (file)

Method: (setf process-lockable-locked?) NEW-VALUE (PROCESS-LOCKABLE process-lockable)

automatically generated writer method

Source

lock.lisp (file)

Generic Function: process-lockable-targets PROCESS-LOCKABLE

Calculates the list of ADDRESSes to acquire recursive locks from when PROCESS-LOCKABLE receives a lock request.

Package

aether

Source

lock.lisp (file)

Generic Function: process-peruse-inbox? OBJECT

Generic Function: (setf process-peruse-inbox?) NEW-VALUE OBJECT

Package

aether

Methods

Method: process-peruse-inbox? (PROCESS process)

Method: (setf process-peruse-inbox?) NEW-VALUE (PROCESS process)

Defaults to T, which means that the ‘PROCESS’ will search through the whole inbox when trying to find a match for clause. Otherwise, the ‘PROCESS’ will only look at the first message in the inbox. Essentially toggles between clause-order precedence and inbox-order predence.

Source

process.lisp (file)

6.1.5 Structures

Structure: address ()

Signifies a channel over which objects can communicate.

NOTE: The SECRET field is "optional", in that only processes that possess the secret can receive on and unregister the channel, but all processes—including those without the secret—can send on the channel.

Package

aether

Source

message.lisp (file)

Direct superclasses

structure-object (structure)

Direct methods

print-object (method)

Direct slots

Slot: courier

Initform

(aether::courier-id aether:*local-courier*)

Readers

address-courier (function)

Writers

(setf address-courier) (function)

Slot: channel

Readers

address-channel (function)

Writers

(setf address-channel) (function)

Slot: secret

Readers

address-secret (function)

Writers

(setf address-secret) (function)

Structure: broadcast-frame ()

Data frame for a ‘BROADCAST’ operation. The ‘ABORTING?’ flag is used to signal to a ‘BROADCAST’ or ‘CONVERGECAST’ command to terminate immediately. If the operation doesn’t abort, the ‘MESSAGE’ is broadcasted to ‘TARGETS’. If we are awaiting replies from the broadcast, we can set ‘HANDLE-RTS?’ to T if we want to pass a ‘:RETURNED?’ keyword argument to ‘WITH-REPLIES’ (and thus handle RTSes gracefully).

Package

aether

Source

cast.lisp (file)

Direct superclasses

structure-object (structure)

Direct subclasses

convergecast-frame (structure)

Direct slots

Slot: aborting?

Type

boolean

Readers

broadcast-frame-aborting? (function)

Writers

(setf broadcast-frame-aborting?) (function)

Slot: handle-rts?

Type

boolean

Readers

broadcast-frame-handle-rts? (function)

Writers

(setf broadcast-frame-handle-rts?) (function)

Slot: message

Type

(or null aether:message)

Readers

broadcast-frame-message (function)

Writers

(setf broadcast-frame-message) (function)

Slot: targets

Type

list

Readers

broadcast-frame-targets (function)

Writers

(setf broadcast-frame-targets) (function)

Structure: convergecast-frame ()

Data frame for a ‘CONVERGECAST’ operation. The ‘INPUT’ is the value calculated at the current level of recursion, to be passed to ‘FUNC’ along with the ‘REPLIES’ from the subsequent level of recursion. The value V passed up is determined as V = (FUNCALL FUNC INPUT REPLIES), and thus the definition of ‘FUNC’ should be something like:

DEFUN FUNC INPUT REPLIES

Where ‘REPLIES’ is assumed to be a ‘LIST’. Additionally, when ‘HANDLE-RTS?’ is true, ‘FUNC’ should be constructed to handle NIL values in ‘INPUT’ or ‘REPLIES’ gracefully. Inherits from ‘BROADCAST-FRAME’.

Package

aether

Source

cast.lisp (file)

Direct superclasses

broadcast-frame (structure)

Direct slots

Slot: func

Type

(or null function)

Readers

convergecast-frame-func (function)

Writers

(setf convergecast-frame-func) (function)

Slot: input

Readers

convergecast-frame-input (function)

Writers

(setf convergecast-frame-input) (function)

Structure: courier ()

A component in the message-passing apparatus.

‘QUEUE’: The receive queue of messages which have not yet been forwarded or stored. Each entry is of the form (COURIER-ID CHANNEL &REST PAYLOAD).
‘INBOXES’: A hash table mapping channels serviced by this courier to mailbox queues.
‘SECRETS’: A hash table mapping channels serviced by this courier to the private sigils used to distinguish mailbox owners.
‘ID’: A unique identifier for this courier. WARNING: Expect subclasses of ‘COURIER’ to require specific types and values here.
‘NEIGHBORS’: Used to store routing information. WARNING: By default, this is a hash mapping courier ‘ID’s in the network to their object instances. Expect subclasses of ‘COURIER’ to install different types and values here.

Package

aether

Source

message.lisp (file)

Direct superclasses

structure-object (structure)

Direct subclasses

courier-gridded (structure)

Direct methods

• handle-object (method)
• courier-courier->route (method)
• print-object (method)

Direct slots

Slot: queue

Initform

(aether:make-q)

Readers

courier-queue (function)

Writers

(setf courier-queue) (function)

Slot: inboxes

Initform

(make-hash-table :test (quote eq))

Readers

courier-inboxes (function)

Writers

(setf courier-inboxes) (function)

Slot: secrets

Initform

(make-hash-table :test (quote eq))

Readers

courier-secrets (function)

Writers

(setf courier-secrets) (function)

Slot: processing-clock-rate

Initform

aether::*courier-processing-clock-rate*

Readers

courier-processing-clock-rate (function)

Writers

(setf courier-processing-clock-rate) (function)

Slot: default-routing-time-step

Initform

aether::*routing-time-step*

Readers

courier-default-routing-time-step (function)

Writers

(setf courier-default-routing-time-step) (function)

Slot: id

Initform

(gensym)

Readers

courier-id (function)

Writers

(setf courier-id) (function)

Slot: neighbors

Initform

(make-hash-table)

Readers

courier-neighbors (function)

Writers

(setf courier-neighbors) (function)

Structure: event ()

Wrapper for a particular event.

Package

aether

Source

event.lisp (file)

Direct superclasses

structure-object (structure)

Direct slots

Slot: callback

Readers

event-callback (function)

Writers

(setf event-callback) (function)

Slot: time

Type

(rational 0)

Initform

0

Readers

event-time (function)

Writers

(setf event-time) (function)

Structure: message ()

Base type for messages transmitted along ‘COURIER’s.

Package

aether

Source

message.lisp (file)

Direct superclasses

structure-object (structure)

Direct subclasses

• message-rts (structure)
• message-rpc-done (structure)
• message-lock (structure)
• message-unlock (structure)

Direct slots

Slot: reply-channel

Type

(or null aether:address)

Readers

message-reply-channel (function)

Writers

(setf message-reply-channel) (function)

Slot: message-id

Type

symbol

Initform

(gensym "message")

Readers

message-message-id (function)

Writers

(setf message-message-id) (function)

Structure: message-lock ()

Sent to establish a lock.

Package

aether

Source

lock.lisp (file)

Direct superclasses

message (structure)

Direct methods

handle-message-lock (method)

Structure: message-rpc-done ()

Reply when an RPC message finishes.

Package

aether

Source

message.lisp (file)

Direct superclasses

message (structure)

Direct slots

Slot: result

Readers

message-rpc-done-result (function)

Writers

(setf message-rpc-done-result) (function)

Structure: message-rts ()

This message is generated as a fresh automatic response when an original message is sent to a nonexistent (or closing) mailbox.

If the original message’s REPLY-CHANNEL is not set, no MESSAGE-RTS object is built.

NOTE: "RTS" is short for "Return To Sender".

Package

aether

Source

message.lisp (file)

Direct superclasses

message (structure)

Direct methods

handle-message-rts (method)

Structure: simulation ()

Container for a set of EVENTs to be processed as part of a simulation.

CONTENTS: The set of EVENTs. This field is not for direct access; instead, add events using SIMULATION-ADD-EVENT.

HORIZON: The timestamp before which all events have been simulated. Ensures that a SIMULATION has a fixed history.

Package

aether

Source

event.lisp (file)

Direct superclasses

structure-object (structure)

Direct slots

Slot: contents

Type

list

Readers

simulation-contents (function)

Writers

(setf simulation-contents) (function)

Slot: horizon

Type

(real 0)

Initform

0

Readers

simulation-horizon (function)

Writers

(setf simulation-horizon) (function)

6.1.6 Classes

Class: process ()

Models an individual concurrently-executing process. On each tick, a ‘PROCESS’ first checks its public mailbox for messages matched by ‘DEFINE-MESSAGE-DISPATCH’ and, if an appropriate message is found, that message is processed. If no matching message is found, the first command in ‘PROCESS-COMMAND-STACK’ is processed instead, according to the semantics defined by ‘DEFINE-PROCESS-UPKEEP’.

IMPORTANT NOTE: Use #’SPAWN-PROCESS to generate a new PROCESS object.

Package

aether

Source

process.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses

• process-message-emissary (class)
• process-lockable (class)

Direct methods

• process-upkeep (method)
• process-upkeep (method)
• handle-object (method)
• handle-message-rts (method)
• print-object (method)
• process-peruse-inbox? (method)
• process-peruse-inbox? (method)
• process-exhaust-inbox? (method)
• process-exhaust-inbox? (method)
• process-debug? (method)
• process-debug? (method)
• process-data-stack (method)
• process-data-stack (method)
• process-command-stack (method)
• process-command-stack (method)
• process-clock-rate (method)
• process-clock-rate (method)
• process-key (method)
• process-key (method)
• process-courier (method)
• process-courier (method)

Direct slots

Slot: process-courier

Holds a reference to the ‘COURIER’ which services this ‘PROCESS’.

Initargs

:process-courier

Initform

aether:*local-courier*

Readers

process-courier (generic function)

Writers

(setf process-courier) (generic function)

Slot: process-key

Holds the ‘PROCESS’s ‘ADDRESS’ on which it receives messages. (Use ‘PROCESS-PUBLIC-ADDRESS’ to extract an ‘ADDRESS’ to be used to send messages to this ‘PROCESS’.)

Initargs

:process-key

Initform

(aether:register)

Readers

process-key (generic function)

Writers

(setf process-key) (generic function)

Slot: process-clock-rate

The number of times per unit of ‘SIMULATION’ time that this ‘PROCESS’ gets to act.

Initargs

:process-clock-rate

Readers

process-clock-rate (generic function)

Writers

(setf process-clock-rate) (generic function)

Slot: process-command-stack

A stack populated with the instructions yet to be executed by this PROCESS. Modify this using ‘PROCESS-CONTINUATION’.

Initform

(sb-int:quasiquote ((aether:start)))

Readers

process-command-stack (generic function)

Writers

(setf process-command-stack) (generic function)

Slot: process-data-stack

A stack populated with data, typically "data frames" pushed and popped by sequences of related commands.

Readers

process-data-stack (generic function)

Writers

(setf process-data-stack) (generic function)

Slot: process-debug?

A boolean flag. If T, debug messages are logged.

Initargs

:debug?

Readers

process-debug? (generic function)

Writers

(setf process-debug?) (generic function)

Slot: process-exhaust-inbox?

Defaults to T, which means that the ‘PROCESS’ will go through its entire message queue in a single clock tick, and then (in the same tick) take an action specified by the command stack. Otherwise, the ‘PROCESS’ will immediately execute a command after handling either zero or one message(s).

Type

boolean

Initargs

:process-exhaust-inbox?

Initform

t

Readers

process-exhaust-inbox? (generic function)

Writers

(setf process-exhaust-inbox?) (generic function)

Slot: process-peruse-inbox?

Defaults to T, which means that the ‘PROCESS’ will search through the whole inbox when trying to find a match for clause. Otherwise, the ‘PROCESS’ will only look at the first message in the inbox. Essentially toggles between clause-order precedence and inbox-order predence.

Type

boolean

Initargs

:process-peruse-inbox?

Initform

t

Readers

process-peruse-inbox? (generic function)

Writers

(setf process-peruse-inbox?) (generic function)

Class: process-lockable ()

A PROCESS which supports recursive locking.

Package

aether

Source

lock.lisp (file)

Direct superclasses

process (class)

Direct methods

• process-upkeep (method)
• process-upkeep (method)
• process-upkeep (method)
• process-upkeep (method)
• process-upkeep (method)
• handle-message-lock (method)
• process-lockable-done-signal (method)
• process-lockable-done-signal (method)
• process-lockable-locked? (method)
• process-lockable-locked? (method)
• process-lockable-aborting? (method)
• process-lockable-aborting? (method)

Direct slots

Slot: aborting?

Type

boolean

Readers

process-lockable-aborting? (generic function)

Writers

(setf process-lockable-aborting?) (generic function)

Slot: locked?

Type

boolean

Readers

process-lockable-locked? (generic function)

Writers

(setf process-lockable-locked?) (generic function)

Slot: done-signal

Readers

process-lockable-done-signal (generic function)

Writers

(setf process-lockable-done-signal) (generic function)

Slot: downward-rx-latches

Type

list

Slot: downward-tx-latches

Type

list

Slot: upward-rx-latch

Type

(or null aether:address)

Slot: upward-tx-latch

Type

(or null aether:address)

6.2 Internal definitions

6.2.1 Special variables

Special Variable: *courier-processing-clock-rate*

Package

aether

Source

message.lisp (file)

Special Variable: *dereferencing-table*

Holds a hash map from ADDRESS objects to the Lisp objects that own them.

Package

aether

Source

dereference.lisp (file)

Special Variable: *message-traces*

Houses information related to traces.

Package

aether

Source

trace.lisp (file)

Special Variable: *routing-time-step*

Package

aether

Source

message.lisp (file)

6.2.2 Macros

Macro: %install-repeat-until (&body REPEATER-BODY) (&body FINALIZER-BODY)

Irreversibly transfers control from the current command by replacing it with a ‘:REPEAT-UNTIL’ command with the indicated ‘REPEATER’ and ‘FINALIZER’.

NOTE: %INSTALL-REPEAT-UNTIL is not available outside the body of DEFINE-PROCESS-UPKEEP.

Package

aether

Source

dpu-helpers.lisp (file)

Macro: assoc-default ITEM ALIST-PLACE DEFAULT-FORM &rest KWARGS

Package

aether

Source

utilities.lisp (file)

Macro: define-dpu-flet FUNCTION-NAME ARGUMENT-LIST &body BODY

Defines a local function to be used inside of DEFINE-PROCESS-UPKEEP.

NOTE: Automatically binds ACTIVE?, NOW, and PROCESS-NAME to their values from within D-P-U.

Package

aether

Source

process.lisp (file)

Macro: define-dpu-macro MACRO-NAME ARGUMENT-LIST &body BODY

Defines a local macro to be used inside of DEFINE-PROCESS-UPKEEP.

NOTE: Automatically binds PROCESS-NAME and NOW to their values from within D-P-U.

Package

aether

Source

process.lisp (file)

Macro: hash-let (BINDING KEY TABLE DEFAULT-FORM) &body BODY

Like GETHASH, except modifies the table.

Package

aether

Source

utilities.lisp (file)

Macro: with-traces () &body BODY

Enable tracing over a region of code.

Package

aether

Source

trace.lisp (file)

6.2.3 Functions

Function: %dpu-flet-definitions &key ACTIVE? NOW PROCESS-NAME

This function produces a list of local function (re)definitions to be supplied in the body of DEFINE-PROCESS-UPKEEP.

NOTE: LOG-ENTRY is treated separately.

Package

aether

Source

process.lisp (file)

Function: %dpu-macrolet-definitions &key PROCESS-NAME NOW

This function produces a list of local macro definitions to be supplied in the body of DEFINE-PROCESS-UPKEEP.

Package

aether

Source

process.lisp (file)

Function: %make-courier-gridded &key (QUEUE QUEUE) (INBOXES INBOXES) (SECRETS SECRETS) (PROCESSING-CLOCK-RATE PROCESSING-CLOCK-RATE) (DEFAULT-ROUTING-TIME-STEP DEFAULT-ROUTING-TIME-STEP) (ID ID) (NEIGHBORS NEIGHBORS)

Package

aether

Source

network.lisp (file)

Function: %make-simulation &key (CONTENTS CONTENTS) (HORIZON HORIZON)

Package

aether

Source

event.lisp (file)

Function: address-channel INSTANCE

Function: (setf address-channel) VALUE INSTANCE

Package

aether

Source

message.lisp (file)

Function: address-courier INSTANCE

Function: (setf address-courier) VALUE INSTANCE

Package

aether

Source

message.lisp (file)

Function: address-p OBJECT

Package

aether

Source

message.lisp (file)

Function: address-secret INSTANCE

Function: (setf address-secret) VALUE INSTANCE

Package

aether

Source

message.lisp (file)

Function: broadcast-frame-aborting? INSTANCE

Function: (setf broadcast-frame-aborting?) VALUE INSTANCE

Package

aether

Source

cast.lisp (file)

Function: broadcast-frame-handle-rts? INSTANCE

Function: (setf broadcast-frame-handle-rts?) VALUE INSTANCE

Package

aether

Source

cast.lisp (file)

Function: broadcast-frame-message INSTANCE

Function: (setf broadcast-frame-message) VALUE INSTANCE

Package

aether

Source

cast.lisp (file)

Function: broadcast-frame-p OBJECT

Package

aether

Source

cast.lisp (file)

Function: broadcast-frame-targets INSTANCE

Function: (setf broadcast-frame-targets) VALUE INSTANCE

Package

aether

Source

cast.lisp (file)

Function: check-key-secret ADDRESS

Asserts that the SECRET stored in ADDRESS matches that recorded by the attendant COURIER.

Package

aether

Source

message.lisp (file)

Function: convergecast-frame-aborting? INSTANCE

Function: (setf convergecast-frame-aborting?) VALUE INSTANCE

Package

aether

Source

cast.lisp (file)

Function: convergecast-frame-func INSTANCE

Function: (setf convergecast-frame-func) VALUE INSTANCE

Package

aether

Source

cast.lisp (file)

Function: convergecast-frame-handle-rts? INSTANCE

Function: (setf convergecast-frame-handle-rts?) VALUE INSTANCE

Package

aether

Source

cast.lisp (file)

Function: convergecast-frame-input INSTANCE

Function: (setf convergecast-frame-input) VALUE INSTANCE

Package

aether

Source

cast.lisp (file)

Function: convergecast-frame-message INSTANCE

Function: (setf convergecast-frame-message) VALUE INSTANCE

Package

aether

Source

cast.lisp (file)

Function: convergecast-frame-p OBJECT

Package

aether

Source

cast.lisp (file)

Function: convergecast-frame-targets INSTANCE

Function: (setf convergecast-frame-targets) VALUE INSTANCE

Package

aether

Source

cast.lisp (file)

Function: copy-address INSTANCE

Package

aether

Source

message.lisp (file)

Function: copy-broadcast-frame INSTANCE

Package

aether

Source

cast.lisp (file)

Function: copy-convergecast-frame INSTANCE

Package

aether

Source

cast.lisp (file)

Function: copy-courier INSTANCE

Package

aether

Source

message.lisp (file)

Function: copy-courier-gridded INSTANCE

Package

aether

Source

network.lisp (file)

Function: copy-event INSTANCE

Package

aether

Source

event.lisp (file)

Function: copy-grid-neighbors INSTANCE

Package

aether

Source

network.lisp (file)

Function: copy-logger INSTANCE

Package

aether

Source

logger.lisp (file)

Function: copy-message INSTANCE

Package

aether

Source

message.lisp (file)

Function: copy-message-lock INSTANCE

Package

aether

Source

lock.lisp (file)

Function: copy-message-rpc-done INSTANCE

Package

aether

Source

message.lisp (file)

Function: copy-message-rts INSTANCE

Package

aether

Source

message.lisp (file)

Function: copy-message-unlock INSTANCE

Package

aether

Source

lock.lisp (file)

Function: copy-simulation INSTANCE

Package

aether

Source

event.lisp (file)

Function: copy-tracer INSTANCE

Package

aether

Source

trace.lisp (file)

Function: courier-default-routing-time-step INSTANCE

Function: (setf courier-default-routing-time-step) VALUE INSTANCE

Package

aether

Source

message.lisp (file)