Module io.github.brantunger.unruly.core
Package io.github.brantunger.unruly.api.language

Interface Session

All Superinterfaces:
AutoCloseable
public interface Session extends AutoCloseable
A language's state for one run of a rule list at a time, such as a single-threaded interpreter context. Compiled conditions and actions are shared by every run, so whatever changes while an expression runs belongs in a session.

The engine creates sessions with ExpressionCompiler.newSession(): one for each language a copy of the rules uses. It makes a copy when a run needs one and none is idle, and, for an engine built with copiesAtLoad(n), makes n copies when the rules load, each session prepared with ExpressionCompiler.warmUp(Session). A run borrows a copy that no other run is using, so a session is used by one run at a time, though possibly on different threads one after another, and every condition and action of that language in the run gets the same session. The engine keeps idle copies for later runs, and closes a session once it no longer needs it: when it drops a copy of the rules, when load() has replaced the rules and no run is still using them, or when the engine is closed.

A language whose compiled expressions are safe to run on several threads at once, and that keeps no other state between runs, returns none().

Implemented by expression languages. A method added to this interface is a default method, so an existing language keeps compiling and working.

See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    default void
    close()
    Releases what the session holds.
    static Session
    none()
    Returns the session of a language that keeps no state between runs.

  • Method Details

    • none

      static Session none()
      Returns the session of a language that keeps no state between runs. Closing it does nothing.
      Returns:
      The shared empty session

    • close

      default void close()
      Releases what the session holds. The engine calls it once, when no run is using the session, on whichever thread finishes with it: the run's thread, or the thread that calls load() or close() when the session is idle. A language whose runtime is bound to a thread must not assume which. By default, does nothing. Anything it throws is logged at WARN, unless a run() or load() it started logged it already, and the engine still closes the other sessions and compilers it is closing. Only a fatal Error then fails the run, load() or close(): it's rethrown unchanged, unless a fatal error of the call's own came first. An InterruptedException in the cause chain of what it throws, or suppressed there, puts back the interrupt status of the thread that closes it, which can be a run's thread, so a run on that thread, such as the outer run of a nested one, then stops as interrupted.
      Specified by:
      close in interface AutoCloseable