Applies f to x and returns the result.

f must be the ID of an object in the object store of the form E_Function f' (and thus f' of ML type data -> data).

x is serialized and transferred to the Isabelle process, the value f' x is computed, serialized and transferred back.

By definition of the type Isabelle.Data, x can be a tree containing integers, strings, and object IDs. When transferring an object ID to the Isabelle process, it is replaced by the object (exception) that is referred by the ID. And similarly, objects (exceptions) in the return value are added to the object store and replaced by IDs upon transfer to the Scala side.

This behavior gives rise to two simple use patterns:

Retrieving values: Say tree is some algebraic data type on the ML side, Tree is a corresponding Scala class, encode : tree -> data is a function that encodes a tree as data (using the DList, DInt, and DString constructors only), and E_Tree of tree is an exception type to store trees in the object store. Then we can define a function for retrieving a tree from the object store to Scala as follows:

val encodeID : Future[ID] = isabelle.storeValue("fn DObject (E_Tree tree) => encode tree")
def decode(data: Data) : Tree = ??? // The opposite of the ML function encode
def retrieve(id: ID) : Tree = {
  // Apply encode to the element referenced by id, result is an encoding of the tree as Data
  val dataFuture : Future[Data] = isabelle.applyFunction(encodeID, DObject(id))
  // For simplicitly, we force synchronous execution
  val data : Data = Await.result(dataFuture, Duration.Inf)
  decode(data)
}

Storing values: Continuing the above example, say decode : data -> tree is an ML function that decodes trees (inverse of encode above). Then we can store trees in the object store from Scala using the following function store:

val decodeID : Future[ID] = isabelle.storeValue("fn data => DObject (E_Tree (decode data))")
def encode(tree: Tree) : Data = ??? // The opposite of the ML function decode
def store(tree: Tree) : ID = {
  // Apply ML-decode to the Scala-encoded tree, store it in the object store, and return the ID (inside a Data)
  val dataFuture : Future[Data] = isabelle.applyFunction(decodeID, encode(tree))
  // For simplicitly, we force synchronous execution
  val data : Data = Await.result(dataFuture, Duration.Inf)
  // get the ID inside the returned data (referring to the tree object in the object store)
  val DObject(id) = data
  id
}

Of course, arbitrary combinations of these two ideas are possible. For example, one could have a Scala data structure that contains IDs of objects still on the ML side. These data structures can be serialized and deserialized similar to the above example, using the fact that the type Isabelle.Data allows IDs to occur anywhere in the tree.

Objects added to the object store by this mechanism are garbage collected on the ML side when the corresponding IDs are not used any more on the Scala side.

This approach is very low level. In particular, there is no type system support to ensure that the IDs contained in the serialized data actually refer to objects of the right type. A higher level typesafe approach for accessing data in the object store is given by de.unruh.isabelle.mlvalue.MLValue (see there). However, MLValues internally use the mechanism described here to transfer data to/from the Isabelle process. Thus, to add support for MLValues of new types, the applyFunction needs to be used.

Kills the running Isabelle process. After this, no more operations on values in the object store are possible. Futures corresponding to already running computations will throw an IsabelleDestroyedException.

Executes the ML code ml in the Isabelle process.

WARNING: This has a global effect on the Isabelle process because it modifies the ML name space.

Definitions made in ml affect the global Isabelle name space. This is intended mostly for defining new types. To create values (e.g., if ml is the code of a function that should be executed), preferably use storeValue which creates anonymous values in the object store. The ML code is executed in a context where the structure Control_Isabelle is not opened (i.e., you have to write Control_Isabelle.E_Int instead of E_Int).

Executes the ML expression ml in the Isabelle process.

WARNING: This has a global effect on the Isabelle process because it modifies the ML name space.

The expression must be of ML type exn. The result of evaluating the expression is added to the object store. The ML code is executed in a context where the structure Control_Isabelle is opened (i.e., you can write E_Int instead of Control_Isabelle.E_Int).

Example: storeValue("exception E_Term of term") (this is actually done by de.unruh.isabelle.pure.Term).

In code that is supposed to support multiple instances of Isabelle, it can be cumbersome to keep track in which instances a given ML code fragment was already executed. See OperationCollection for a helper class to facilitate that.