Table of Contents
A Perper application is composed of many Agents -- encapsulated distributed objects that can hold State, processes Executions, and produce or consume Streams. All of those are made available through Object Capabilities, meaning that the only way to be able to use an Agent, State, Execution, or Stream is through a reference to it.
Agents are similar to classes in conventional OOP programming. They can be instantiated, producing an Agent Instance (confusingly often also called an "Agent"); they can hold State; they can expose Delegates to be called via Executions; and they can interact with Streams. As such, agents are the basic unit of encapsulation within a Perper application.
An Agent Instance is an individual instance of an Agent.
"Agent Type" is a term used for disambiguation in cases when "Agent" might be misinterpreted to mean "Agent Instance".
In Perper, Executions are used to model anything that needs to run, is currently running, or has just finished running. Every Execution is associated with an Agent Instance and may contain arbitrary parameters from the caller, or, once it's finished, a result or error value.
Keeping in our analogy with typical OOP programming, Executions take on roughly the role of stack frames.
The Delegate of an Executions corresponds to the method name that is being called on the Agent Instance.
States are a distributed key-value stores that can be accessed by Executions in order to persist data. They ensure that even if a machine or a process dies, execution can continue when the affected processes are restarted elsewhere.
An Agent Instance can own multiple States.
Streams are similar to States in that they allow for data to be persisted. However, unlike States, they also allow for listeners to wait until there is new data available for reading.
Perper allows for the construction of arbitrary stream graphs between Executions at runtime, including cyclic graphs.
Every Stream can have multiple Executions writing to it and multiple Executions listening for new items. Every listener receives the whole contents of the Stream.
A Stream Item is a value inside a Stream. Every Stream Item needs a monotonically increasing integer key, which allows all listeners to end up with the same order of Items inside the Stream.
Streams marked as "packed" allow for items to be written out of order, as long as writers use consecutive keys -- those are, for example, useful for modeling time series data.
Streams marked as "ephemeral" delete their Items after the all listeners have finished processing them. In contrast, "persistent" Streams do not delete its items automatically.
A Stream can be indexed, and later queried, allowing for the fast retrieval of items from the Stream without needing to iterate all of it.
Perper makes use of Object Capabilities for security. The only way for user code to access an object (be it an Agent, or a Stream, or something else) in a Perper system is through a reference to it. Such a reference can be obtained only by either directly creating the object or receiving a reference to it.
Object references can be passed between Executions as parameters or return values, stored inside States, or sent along Streams.
You can read more about the Object-Capability Model on Wikipedia.