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
  • package basis

    A home for types that are needed more or less pervasively.

    A home for types that are needed more or less pervasively.

    @author Bernard Sufrin, Oxford
    $Revision: 228 $
    $Date: 2016-03-04 16:11:56 +0000 (Fri, 04 Mar 2016)
  • package channel

    Specifies primitive (non-alternation-capable) ports and channels; and implements several channel types.

  • package component

    A collection of several process-generators that (mostly) yield processes to work on (or produce) finite or infinite streams of values presented as channel.

    A collection of several process-generators that (mostly) yield processes to work on (or produce) finite or infinite streams of values presented as channel. All are designed to terminate cleanly -- 'i.e.' to closeIn or closeOut all the channel.that they communicate on in the appropriate direction for the type of port.

    Some of these components were inspired by (or copied from) components from the Plug'n'Play collection of JCSP (without necessarily retaining the P'n'P names).

    @version 03.20120824
    @author Bernard Sufrin, Oxford
    $Revision: 247 $
    $Date: 2017-10-20 15:00:00 +0100 (Fri, 20 Oct 2017) $
  • package debug
  • package lock
  • package monitor
  • package process
  • package semaphore
  • DebuggerFormat
  • Guarded
  • NanoTime
  • coerce
p

io

threadcso

package threadcso

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) $
Linear Supertypes
AnyRef, Any
Ordering
  1. Alphabetic
  2. By Inheritance
Inherited
  1. threadcso
  2. AnyRef
  3. Any
  1. Hide All
  2. Show All
Visibility
  1. Public
  2. All

Type Members

  1. type ![T] = OutPort[T]
  2. type ?[T] = InPort[T]
  3. type Barrier = threadcso.lock.Barrier
  4. type Chan[T] = threadcso.alternation.channel.Chan[T]

    Type of an alt-capable channel as returned by the standard factory methods of the io.threadcso API.

  5. type CombiningBarrier[T] = threadcso.lock.CombiningBarrier[T]
  6. type Condition = java.util.concurrent.locks.Condition
  7. type Debuggable = threadcso.debug.REGISTRY.Debuggable
  8. class DebuggerFormat extends Debuggable

    A concrete debuggable class whose toString method evaluates the expression theFormat whenever it is called (normally by the debugger).

    A concrete debuggable class whose toString method evaluates the expression theFormat whenever it is called (normally by the debugger). This is a notationally convenient way of constructing a debugger-registerable object that can be used to show (part of) the state of a running process.

    For example, the copy process below keeps track of the number of values it has copied, and of the last value. It registers a DebuggerFormat with the debugger, so that if the debugger is invoked during the repeat, then the current state of the process will be shown when the debugger is showing its registered objects.

    def mycopy[T](in: ?[T], out: ![T]) = proc
    { var buf = in.nothing
      var n   = 0
      val format = new DebuggerFormat(s"$n: $buf")
      format.withDebugger(true)
      {
        repeat { buf=in?(); out!buf; n+=1 }
      }
    }

    The method withDebugger (see below) is a convenient way of constructing and registering a debugger format to be used during the evaluation of an expression.

  9. type FairMonitor = threadcso.monitor.FairMonitor
  10. type Flag = threadcso.semaphore.Flag
  11. implicit class Guarded extends AnyRef

    This implicit class is used in the implementation of guarded I/O-event notation.

    This implicit class is used in the implementation of guarded I/O-event notation. The operator && replaced the operator &&& in CSO version 1.2.

    See also

    io.threadcso.alternation

  12. type Latch = threadcso.semaphore.Latch
  13. type Milliseconds = Long
  14. type Monitor = threadcso.monitor.Monitor
  15. implicit class NanoTime extends AnyRef

    This implicit class provides additional methods that support the legible formatting of the Nanoseconds value _elapsed (which can be negative).

  16. type Nanoseconds = Long

    Provides the source location to pass as (implicit loc: SourceLocation) parameters

  17. type PROC = threadcso.process.PROC

    Process type

  18. type Semaphore = threadcso.semaphore.Semaphore

Value Members

  1. def Alternation(events: Event)(implicit loc: SourceLocation.SourceLocation): Run

    Compile an alternation.

    Compile an alternation. This can be useful for making a strength-reduction optimization by taking the compilation/normalization of the body of the alternation outside a loop. val a = Alternation(events); ... ; a.alt (where a is a variable not occuring in ...) is always equivalent to ... alt(events). Likewise for prialt, priserve, and serve.

    Annotations
    @inline()
  2. def Alternation(debug: Boolean, events: Event)(implicit loc: SourceLocation.SourceLocation): Run

    Compile an alternation.

    Compile an alternation. This can be useful for making a strength-reduction optimization by taking the compilation/normalization of the body of the alternation outside a loop. val a = Alternation(events); ... ; a.alt (where a is a variable not occuring in ...) is always equivalent to ... alt(events). Likewise for prialt, priserve, and serve.

    Annotations
    @inline()
  3. def Barrier(n: Int, name: String = ""): Barrier

    Factory for Barriers

  4. val BooleanSemaphore: threadcso.semaphore.BooleanSemaphore.type

    Factory for BooleanSemaphores.

    Factory for BooleanSemaphores. @see io.threadcso.semaphore.BooleanSemaphore

  5. def CombiningBarrier[T](n: Int, e: T, f: (T, T) ⇒ T, name: String = ""): CombiningBarrier[T]

    Factory for CombiningBarriers

  6. val CountingSemaphore: threadcso.semaphore.CountingSemaphore.type

    Factory for CountingSemaphores.

    Factory for CountingSemaphores. @see io.threadcso.semaphore.CountingSemaphore

  7. val Day: Nanoseconds

    Number of nanoseconds in a day: n*Day is n days expressed as nanoseconds

  8. val Flag: threadcso.semaphore.Flag.type

    Factory for Flags.

  9. val Hour: Nanoseconds

    Number of nanoseconds in an hour: n*Hour is n hours expressed as nanoseconds

  10. val Latch: threadcso.semaphore.Latch.type

    Factory for Latches

  11. def ManyMany[T]: SharedAltCapableChannel[T]
  12. def ManyMany[T](name: String = null): SharedAltCapableChannel[T]

    Abbreviation for N2N(0, 0, name)

  13. def ManyOne[T]: SharedAltCapableChannel[T]
  14. def ManyOne[T](name: String = null): SharedAltCapableChannel[T]

    Abbreviation for N2N(0, 1, name)

  15. val Min: Nanoseconds

    Number of nanoseconds in a minute: n*Min is n minutes expressed as nanoseconds

  16. def Monitor(fair: Boolean, name: String = null): AbstractMonitor

    A new AbstractMonitor object (either a FairMonitor or a Monitor) whose lock-acquisition policy is as specified by fair.

  17. def N2N[T](writers: Int, readers: Int, name: String = null, fairOut: Boolean = false, fairIn: Boolean = false): SharedAltCapableChannel[T]

    Return a synchronous alt-capable channel (with the given name) designed for shared synchronous communication between writers writers, and readers readers.

    Return a synchronous alt-capable channel (with the given name) designed for shared synchronous communication between writers writers, and readers readers. When all writers have invoked the method closeOut (or all readers the method closeIn), the channel closes. If either writers or readers is nonpositive, then the channel can be closed an unbounded number of times in the associated direction.

  18. def N2NBuf[T](size: Int, writers: Int, readers: Int, name: String = null, fairOut: Boolean = false, fairIn: Boolean = false): SharedAltCapableChannel[T]

    Return a buffered alt-capable channel (with the given name) designed for shared communication between writers writers, and readers readers.

    Return a buffered alt-capable channel (with the given name) designed for shared communication between writers writers, and readers readers. When all writers have invoked the method closeOut (or all readers the method closeIn), the channel closes. If either writers or readers is nonpositive, then the channel can be closed an unbounded number of times in the associated direction.

  19. def OneMany[T]: SharedAltCapableChannel[T]
  20. def OneMany[T](name: String = null): SharedAltCapableChannel[T]

    Abbreviation for N2N(1, 0, name)

  21. def OneOne[T]: Chan[T]

    Return a synchronous alt-capable channel (with an automatically-generated name) designed for point-to-point communication.

    Return a synchronous alt-capable channel (with an automatically-generated name) designed for point-to-point communication. There is a (weak) dynamic check against multiple processes writing/reading simultaneously.

  22. def OneOne[T](name: String = null): Chan[T]

    Return a synchronous alt-capable channel (with the given name) designed for point-to-point communication.

    Return a synchronous alt-capable channel (with the given name) designed for point-to-point communication. There is a (weak) dynamic check against multiple processes writing/reading simultaneously.

  23. def OneOneBuf[T](size: Int, name: String = null): Chan[T]

    Return a buffered alt-capable channel (with the given name) designed for communication between a writer and a reader.

    Return a buffered alt-capable channel (with the given name) designed for communication between a writer and a reader. This is functionally equivalent to N2NBuf(size, 1, 1, name).

  24. val SKIP: threadcso.process.PROC

    A process that does nothing.

  25. val Sec: Nanoseconds

    Number of nanoseconds in a second: n*Sec is n seconds expressed as nanoseconds

  26. val after: (⇒ Nanoseconds) ⇒ AfterDeadline

    after syntax for 'alt' bodies

  27. def alt(debug: Boolean, events: Event)(implicit loc: SourceLocation.SourceLocation): Unit

    Execute an alt (while registered with the debugger, if debug)

  28. def alt(events: Event)(implicit loc: SourceLocation.SourceLocation): Unit

    Execute an alternation

  29. def attempt[T](body: ⇒ T)(alternative: ⇒ T): T

    Evaluate body and return its value unless an exception ex is thrown.

    Evaluate body and return its value unless an exception ex is thrown. If ex is a Stopped then evaluate and return the value of alternative, otherwise re-throw ex.

    Annotations
    @inline()
  30. lazy val debugger: DEBUGGER

    The debugger (if it is loaded), else null.

    The debugger (if it is loaded), else null. The debugger's port is specified by the integer N set as a runtime option by -Dio.threadcso.debugger.port=N (the default setting is zero). If N is negative, the debugger is not loaded; if N is zero, the debugger is loaded and made available at some currently-free port on the local host; if N is positive then the debugger is loaded and made available at port N if that port is free.

  31. def exit(code: Int): Unit

    Close down the thread pools, and exit the program, yielding code.

    Close down the thread pools, and exit the program, yielding code.

    Annotations
    @inline()
  32. def exit(): Unit

    Close down the thread pools, and exit the program.

    Close down the thread pools, and exit the program.

    Annotations
    @inline()
  33. def fork(proc: PROC): Handle

    Run the given proc in an acquired thread, and return a handle on the running thread.

    Run the given proc in an acquired thread, and return a handle on the running thread.

    Annotations
    @inline()
  34. def interrupted(): Boolean

    Returns true iff the current thread has been cancelled, and clears the cancelled bit in the thread if so.

  35. val microSec: Nanoseconds

    Number of nanoseconds in a microsecond: n*microSec is n microseconds expressed as nanoseconds

  36. val milliSec: Nanoseconds

    Number of nanoseconds in a millisecond: n*milliSec is n milliseconds expressed as nanoseconds

  37. def milliTime: Milliseconds

    Read the system millisecond timer

    Read the system millisecond timer

    Annotations
    @inline()
  38. val nanoSec: Nanoseconds

    Number of nanoseconds in a nanosecond

  39. def nanoTime: Nanoseconds

    Read the system nanosecond timer

    Read the system nanosecond timer

    Annotations
    @inline()
  40. val orelse: threadcso.alternation.event.orelse.type

    orelse syntax for 'alt' bodies

  41. def par[T](range: Seq[T])(gen: (T) ⇒ PROC): Unit

    Same as par(range.map(gen))

    Same as par(range.map(gen))

    Annotations
    @inline()
  42. def par(procs: Seq[PROC]): Unit

    Run the parallel composition of procs

    Run the parallel composition of procs

    Annotations
    @inline()
  43. def prialt(debug: Boolean, events: Event)(implicit loc: SourceLocation.SourceLocation): Unit

    Execute a prialt (while registered with the debugger, if debug)

  44. def prialt(events: Event)(implicit loc: SourceLocation.SourceLocation): Unit

    Execute an alternation

  45. def priserve(debug: Boolean, events: Event)(implicit loc: SourceLocation.SourceLocation): Unit

    repeatedly execute an alt (while registered with the debugger, if debug)

  46. def priserve(events: Event)(implicit loc: SourceLocation.SourceLocation): Unit

    repeatedly execute an alternation

  47. def proc(body: ⇒ Unit): PROC

    proc { body }

    is a PROC-valued expression denoting a simple process with a made-up name.

    It is, in-effect, a procedure of type ()=>UNIT.

    run(proc { body }) = (proc { body })() = (()=>body)()
    Annotations
    @inline()
  48. def proc(name: String)(body: ⇒ Unit): PROC

    proc ("name") { body }

    is a PROC-valued expression denoting a simple process with the given name.

    Annotations
    @inline()
  49. def repeat(body: ⇒ Unit): Unit

    Iterate body.

    Iterate body. If an exception ex is thrown, then stop the iteration, and unless ex is a Stopped re-throw ex.

    Annotations
    @inline()
  50. def repeat(guard: ⇒ Boolean)(body: ⇒ Unit): Unit

    Iterate body while the evaluation of guard yields true.

    Iterate body while the evaluation of guard yields true. If an exception ex is thrown, then stop the iteration, then unless ex is a Stopped re-throw ex.

    Annotations
    @inline()
  51. def repeatFor[T](it: Iterable[T])(fn: (T) ⇒ Unit): Unit

    repeatFor (it: Iterable[T]) { bv => body } applies the function { bv => body } to each of the elements of an iterator formed from the iterable.

    repeatFor (it: Iterable[T]) { bv => body } applies the function { bv => body } to each of the elements of an iterator formed from the iterable. If an exception ex is thrown, then stop the iteration, then unless ex is a Stopped re-throw ex.

    Annotations
    @inline()
  52. def run(proc: PROC): Unit

    Run the given proc in the current thread.

    Run the given proc in the current thread.

    Annotations
    @inline()
  53. def seconds(secs: Double): Nanoseconds

    Convert a fractional time expressed in seconds to nanoseconds

  54. def serve(debug: Boolean, events: Event)(implicit loc: SourceLocation.SourceLocation): Unit

    repeatedly execute an alt (while registered with the debugger, if debug) -- event choice is fair

  55. def serve(events: Event)(implicit loc: SourceLocation.SourceLocation): Unit

    repeatedly execute an alternation -- ready events are chosen round-robin -- approximating fairness

  56. def sleep(ns: Nanoseconds): Unit

    Sleep for the given number of nanoseconds

    Sleep for the given number of nanoseconds

    Annotations
    @inline()
  57. def sleepms(ms: Milliseconds): Unit

    Sleep for the given number of milliseconds.

    Sleep for the given number of milliseconds.

    Annotations
    @inline()
  58. implicit macro def sourceLocation: SourceLocation.SourceLocation

    Implicit parameter to various methods

  59. val startTime: Nanoseconds

    The value of nanoTime when the entire program was started -- useful only for relative timing.

  60. def stop: Nothing

    Terminate the current process or the current repeat

    Terminate the current process or the current repeat

    Annotations
    @inline()
  61. def withDebuggerFormat[T](theFormat: ⇒ String, register: Boolean = true)(body: ⇒ T): T

    Constructs a DebuggerFormat object from the given format string expression and registers it (if register is true) with the debugger during the evaluation of the body expression.

    Constructs a DebuggerFormat object from the given format string expression and registers it (if register is true) with the debugger during the evaluation of the body expression.

    For example, the copy process below keeps track of the number of values it has copied, and of the last value. If the debugger is invoked during the repeat, then the current state of the process will be shown when the debugger is showing its registered objects.

    def mycopy[T](in: ?[T], out: ![T]) = proc
    { var buf = in.nothing
      var n   = 0
      withDebuggerFormat(s"$n: $buf")
      {
        repeat { buf=in?(); out!buf; n+=1 }
      }
    }
  62. val |: (Seq[ExecutableEvent]) ⇒ ExecutableEventSyntax

    prefix | syntax for 'alt' bodies

  63. def ||[T](range: Seq[T])(gen: (T) ⇒ PROC): PROC

    Same as ||(range.map(gen))

    Same as ||(range.map(gen))

    Annotations
    @inline()
  64. def ||(procs: Seq[PROC]): PROC

    The parallel composition of procs; unless procs is empty, in which case SKIP.

    The parallel composition of procs; unless procs is empty, in which case SKIP.

    Annotations
    @inline()
  65. val μS: Nanoseconds

    Number of nanoseconds in a microsecond: n*μS is n microseconds expressed as nanoseconds

  66. def π(name: String)(body: ⇒ Unit): PROC

    Same as proc(name)(body)

    Same as proc(name)(body)

    Annotations
    @inline()
  67. def π(body: ⇒ Unit): PROC

    Same as proc(body)

    Same as proc(body)

    Annotations
    @inline()
  68. object coerce

    To enable implicit coercion of unit-valued expressions to simple processes: import io.threadcso.coerce.UnitProc.

    To enable implicit coercion of unit-valued expressions to simple processes: import io.threadcso.coerce.UnitProc. For example, in the scope of this coercion, the following process expressions are equivalent:

    (println("foo") || println("bar"))
    
    (proc { println("foo") } || proc { println("bar") })

    CSO neophytes are strongly discouraged from importing this implicit coercion, for it can lead to confusing error messages from the compiler, and confusing behaviour at run-time.

Inherited from AnyRef

Inherited from Any

Ungrouped