Packages

  • package root
    Definition Classes
    root
  • package io

    This is the documentation for the ThreadCSO Library.

    This is the documentation for the ThreadCSO Library. Notable packages include:

    Definition Classes
    root
  • package threadcso

    The standard threadCSO API.

    The standard threadCSO API. Most modules using CSO will need only the declaration:

    import io.threadcso._

    The present version of the ThreadCSO library API is 1.2Rr (for some number r)

    The revision number (Rr) will change if bugs are corrected but the code remains consistent with the previous API. Its minor version number will change if there is a correction to the code that breaks consistency with the previous API. Its major version will change if there is a substantial change in the semantics of an important CSO construct.

    August 2017: changes 1.1 => 1.2

    • renaming of very many internal classes and packages
    • basic channel implementations are more efficient, in some case much more so
    • alternation reliability improved
    • debugger registration of alternations is no longer needed
    • home-grown semaphores can specify which component they are part of: this makes interpreting a stack backtrace very much easier
    • there is a flexible logging system that is compatible with the debugger

    April 2016: changes 1.0 => 1.1

    • Extended rendezvous read operator is now ?? (was ?)
    • Extended rendezvous read event notation is now =??=> (was =?=>>)
    • The notation inport ? f is now equivalent to f(inport?()) This makes for a tidier layout when the function f is an explicit functional expression.

    Feb 1 2017: changes 1.1R1 => 1.1R2

    • Removed dependencies on deprecated Java->Scala functions: replaced with .asJava
    @author Bernard Sufrin, Oxford
    $Revision: 286 $
    $Date: 2017-11-18 17:41:30 +0000 (Sat, 18 Nov 2017) $
    Definition Classes
    io
  • package alternation
    Definition Classes
    threadcso
  • package channel

    This package defines channels that can participate in the CSO alternation constructs.

    This package defines channels that can participate in the CSO alternation constructs.

    I have separated syntax and semantics as far as was practical, given my reluctance to get embroiled with the Scala macro system (it was unstable when the CSO work started)

    An io.threadcso.alternation.Run embodies the state of execution of an alternation.

    The guarded event notation: (guard && port) =...=> { .... } is parsed to a Guarded...Port =...=> ... then to an appropriate class of event. The former is achieved by defining the implicit class io.threadcso.Guarded in the top-level CSO API. This provides the appropriate extension to Boolean.

    @author Bernard Sufrin, Oxford
    $Revision: 240 $
    $Date: 2017-10-13 18:12:11 +0100 (Fri, 13 Oct 2017) $
    Definition Classes
    alternation
  • package event

    This package implements the syntax of the CSO alternation notations, and provides hooks for the semantics of that notation.

    This package implements the syntax of the CSO alternation notations, and provides hooks for the semantics of that notation.

    The body of an alternation specification consists of a sequence (possibly empty) of executable event specifications separated by | and possibly followed by:

    | after(timeout) ==> { ... }

    or

    | orelse ==> { ... }

    or

    | after(timeout) ==> { ... } |  orelse ==> { ... }

    An executable event specification takes one of the following forms:

    outport              =!=>  OutEvent
    (guard && outport)   =!=>  OutEvent
    inport               =?=>  InEvent
    (guard && inport)    =?=>  InEvent
    inport               =??=> InEvent     // extended rendezvous form
    (guard && inport)    =??=> InEvent     // extended rendezvous form

    Concessions to readability: a Chan expression may appear in place of a port expression.

    Events and their effects

    OutEvent form:                        Effect when triggered
    {expr}                                outport!expr
    {expr} ==> { command: Unit }          {outport!expr; command}
    InEvent form:                         Effect when triggered
    { bv => body: Unit }                  {val bv=inport?(); body }

    For an extended rendezvous InEvent the correspondence is

    { bv => body: Unit }                  { inport??({ bv => body}) }
    Definition Classes
    alternation
  • AltAbort
  • IgnorePortEvents
  • LoggingFlags
  • Run
  • Runnable

sealed class Run extends Runnable with debug.REGISTRY.Debuggable

Manages the state of a running alternation construct whose abstract syntax is syntax. If registerWithDebugger is true then the alternation construct is registered with the debugger while it runs. This is for in-extremis debugging of deadlocking CSO code that includes alternations.

Alternations happen in four phases (these phases are almost the same for alt, prialt, serve and priserve constructs), namely: Registration, Waiting, Unregistration, and Execution.

  1. Registration: The current feasibility of all participating events is recorded as UNKNOWNSTATE, INFEASIBLE, or READYSTATE, and their associated ports are marked as being involved in this running alternation construct. An event for a port that is closed at this stage will never become feasible. An event is infeasible if its associated port has been closed, or if its associated guard is false.
  2. Waiting: If, after registration, no READYSTATE event is present, but some events are still feasible, then the alternation will wait (with the appropriate deadline, if there's an after event; and sine-die otherwise) for a port to change state. If there's an after event and the wait timed-out, then the after event is marked to be executed. If no events are feasible by this phase, or if the last feasible event becomes infeasible as a consequence of a state change (because its port closed during the wait), then the orelse path is taken, to wit: the orelse event (if any) is marked to be executed.
  3. Unregistration: All ports of all feasible events are now unregistered from their participation in this running alt. If during this phase any already-feasible events are found to be ready then one of them is chosen and marked for execution. The precise method of choice depends on whether or not the alternation construct is supposed to be fair. In this implementation all but serve alternations choose the first event (in order of appearance in the alternation) found to be ready during unregistration. (Unregistration of feasible events actually takes place in reverse order of appearance in the alternation, giving "higher priority" feasible events a little more time to become ready.)
  4. Execution: When all event ports have been unregistered, then:
    • If a feasible event has been marked for execution, then it is executed; or
    • If after has been marked for execution, then it is executed; or
    • If orelse has been marked for execution, then it is executed (and if the executing alternative is a serve, the serve is terminated)
    • If nothing has been marked for execution, then an alt or prialt will abort; and a serve or priserve will terminate.

The present implementation is highly unadventurous and may be less than optimally efficient, though it is (intended to be) scrutable. My experience has been that alternation is tricky to implement efficiently without introducing race conditions that are hard to track down.

Possible improvements/speedups include:

  • Run the first event found to be ready during registration in an priserve or prialt.
  • Give the programmer more control of the algorithm that chooses fairly between events run during the execution of a serve. The round-robin method is not always effective -- particularly when certain patterns of guarded event are present in the alternation.
  • Distinguish between alt and prialt implementation by using an efficient source of randomness to choose among events that become ready before unregistration.
@author Bernard Sufrin, Oxford,
$Revision: 316 $,
$Date: 2018-01-11 18:18:45 +0000 (Thu, 11 Jan 2018) $
Linear Supertypes
Ordering
  1. Alphabetic
  2. By Inheritance
Inherited
  1. Run
  2. Debuggable
  3. Runnable
  4. AnyRef
  5. Any
  1. Hide All
  2. Show All
Visibility
  1. Public
  2. All

Instance Constructors

  1. new Run(register: Boolean, syntax: Event, loc: SourceLocation.SourceLocation)

    register

    Redundant in the current implementation.

    syntax

    Abstract syntax of the alternation

    loc

    Source loc'n of the alternation (implicit SourceLocation parameter to alt/prialt/serve/priserve)

Value Members

  1. final def !=(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  2. final def ##(): Int
    Definition Classes
    AnyRef → Any
  3. final def ==(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  4. def alt(): Unit

    Run this alternation as an alt

  5. final def asInstanceOf[T0]: T0
    Definition Classes
    Any
  6. def clone(): AnyRef
    Attributes
    protected[java.lang]
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  7. final def eq(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  8. def equals(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  9. def finalize(): Unit
    Attributes
    protected[java.lang]
    Definition Classes
    AnyRef
    Annotations
    @throws( classOf[java.lang.Throwable] )
  10. final def getClass(): Class[_]
    Definition Classes
    AnyRef → Any
  11. def getWaiting: Seq[Thread]

    Returns List(runner) only if the alternation is waiting for an event to become ready; otherwise List().

    Returns List(runner) only if the alternation is waiting for an event to become ready; otherwise List().

    Definition Classes
    RunDebuggable
  12. def hasState: Boolean

    This object has a state worth showing right now: false if showState will do no output.

    This object has a state worth showing right now: false if showState will do no output.

    Definition Classes
    Debuggable
  13. def hashCode(): Int
    Definition Classes
    AnyRef → Any
  14. final def isInstanceOf[T0]: Boolean
    Definition Classes
    Any
  15. val key: StateKey

    This object's key in the registry (if non-negative)

    This object's key in the registry (if non-negative)

    Definition Classes
    Debuggable
  16. final def ne(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  17. final def notify(): Unit
    Definition Classes
    AnyRef
  18. final def notifyAll(): Unit
    Definition Classes
    AnyRef
  19. def notifyPortEvent(theIndex: Int, state: PortState): Unit

    Notification that its state of readiness changed: sent by a port referenced by the theIndexth event of this alternation.

    Notification that its state of readiness changed: sent by a port referenced by the theIndexth event of this alternation. Only CLOSEDSTATE and READYSTATE are ever notified by channel implementations, because only these are of interest to an already-running alternation.

    Definition Classes
    RunRunnable
  20. def prialt(): Unit

    Run this alternation as a prialt

    Run this alternation as a prialt

    Annotations
    @inline()
  21. def priserve(): Unit

    Run this alternation as a priserve

  22. def register(): Unit

    Register this object

    Register this object

    Definition Classes
    Debuggable
  23. def serve(): Unit

    Run this alternation as a serve

  24. def showState(out: PrintWriter): Unit

    Invoked by the debugger to show the current state of this running alternation.

    Invoked by the debugger to show the current state of this running alternation.

    Definition Classes
    RunDebuggable
  25. final def synchronized[T0](arg0: ⇒ T0): T0
    Definition Classes
    AnyRef
  26. def toString(): String
    Definition Classes
    Run → AnyRef → Any
  27. def unregister(): Unit

    Unregister this object

    Unregister this object

    Definition Classes
    Debuggable
  28. final def wait(): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  29. final def wait(arg0: Long, arg1: Int): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  30. final def wait(arg0: Long): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  31. def withDebugger[T](condition: Boolean)(body: ⇒ T): T

    Conditionally register this object with the debugger only for the duration of the evaluation of body.

    Conditionally register this object with the debugger only for the duration of the evaluation of body. To be used as a last resort for the exasperated CSO toolkit debugger.

    Definition Classes
    Debuggable

Inherited from debug.REGISTRY.Debuggable

Inherited from Runnable

Inherited from AnyRef

Inherited from Any

Ungrouped