| Safe Haskell | Safe-Inferred |
|---|---|
| Language | Haskell2010 |
UntypedPlutusCore.Evaluation.Machine.Cek.Internal
Description
The CEK machine.
Synopsis
- data EvaluationResult a
- data CekValue uni fun ann
- data ArgStack uni fun ann
- = EmptyStack
- | ConsStack !(CekValue uni fun ann) !(ArgStack uni fun ann)
- transferArgStack ∷ ArgStack uni fun ann → Context uni fun ann → Context uni fun ann
- data CekUserError
- type CekEvaluationException name uni fun = EvaluationException (MachineError fun) CekUserError (Term name uni fun ())
- newtype CekBudgetSpender uni fun s = CekBudgetSpender {
- unCekBudgetSpender ∷ ExBudgetCategory fun → ExBudget → CekM uni fun s ()
- data ExBudgetInfo cost uni fun s = ExBudgetInfo {
- _exBudgetModeSpender ∷ !(CekBudgetSpender uni fun s)
- _exBudgetModeGetFinal ∷ !(ST s cost)
- _exBudgetModeGetCumulative ∷ !(ST s ExBudget)
- newtype ExBudgetMode cost uni fun = ExBudgetMode {
- unExBudgetMode ∷ ∀ s. ST s (ExBudgetInfo cost uni fun s)
- type CekEmitter uni fun s = DList Text → CekM uni fun s ()
- data CekEmitterInfo uni fun s = CekEmitterInfo {
- _cekEmitterInfoEmit ∷ !(CekEmitter uni fun s)
- _cekEmitterInfoGetFinal ∷ !(ST s [Text])
- newtype EmitterMode uni fun = EmitterMode {
- unEmitterMode ∷ ∀ s. ST s ExBudget → ST s (CekEmitterInfo uni fun s)
- newtype CekM uni fun s a = CekM {}
- data ErrorWithCause err cause = ErrorWithCause {}
- data EvaluationError structural operational
- = StructuralEvaluationError !structural
- | OperationalEvaluationError !operational
- data ExBudgetCategory fun
- = BStep StepKind
- | BBuiltinApp fun
- | BStartup
- data StepKind
- type ThrowableBuiltins uni fun = (PrettyUni uni, Pretty fun, Typeable uni, Typeable fun)
- splitStructuralOperational ∷ Either (EvaluationException structural operational term) a → Either (ErrorWithCause structural term) (EvaluationResult a)
- unsafeSplitStructuralOperational ∷ (PrettyPlc structural, PrettyPlc term, Typeable structural, Typeable term) ⇒ Either (EvaluationException structural operational term) a → EvaluationResult a
- runCekDeBruijn ∷ ThrowableBuiltins uni fun ⇒ MachineParameters CekMachineCosts fun (CekValue uni fun ann) → ExBudgetMode cost uni fun → EmitterMode uni fun → NTerm uni fun ann → (Either (CekEvaluationException NamedDeBruijn uni fun) (NTerm uni fun ()), cost, [Text])
- dischargeCekValue ∷ CekValue uni fun ann → NTerm uni fun ()
- data Context uni fun ann
- = FrameAwaitArg !(CekValue uni fun ann) !(Context uni fun ann)
- | FrameAwaitFunTerm !(CekValEnv uni fun ann) !(NTerm uni fun ann) !(Context uni fun ann)
- | FrameAwaitFunValue !(CekValue uni fun ann) !(Context uni fun ann)
- | FrameForce !(Context uni fun ann)
- | FrameConstr !(CekValEnv uni fun ann) !Word64 ![NTerm uni fun ann] !(ArgStack uni fun ann) !(Context uni fun ann)
- | FrameCases !(CekValEnv uni fun ann) !(Vector (NTerm uni fun ann)) !(Context uni fun ann)
- | NoFrame
- type CekValEnv uni fun ann = RAList (CekValue uni fun ann)
- type GivenCekReqs uni fun ann s = (GivenCekRuntime uni fun ann, GivenCekEmitter uni fun s, GivenCekSpender uni fun s, GivenCekSlippage, GivenCekStepCounter s, GivenCekCosts)
- type GivenCekSpender uni fun s = ?cekBudgetSpender ∷ CekBudgetSpender uni fun s
- data StepCounter (n ∷ Nat) s
- type CounterSize = NumberOfStepCounters + 1
- type TotalCountIndex = NumberOfStepCounters
- type Slippage = Word8
- defaultSlippage ∷ Slippage
- type NTerm uni fun = Term NamedDeBruijn uni fun
- runCekM ∷ ∀ a cost uni fun ann. ThrowableBuiltins uni fun ⇒ MachineParameters CekMachineCosts fun (CekValue uni fun ann) → ExBudgetMode cost uni fun → EmitterMode uni fun → (∀ s. GivenCekReqs uni fun ann s ⇒ CekM uni fun s a) → (Either (CekEvaluationException NamedDeBruijn uni fun) a, cost, [Text])
Documentation
data EvaluationResult a Source #
The parameterized type of results various evaluation engines return.
On the PLC side this becomes (via makeKnown) either a call to Error or
a value of the PLC counterpart of type a.
Constructors
| EvaluationSuccess !a | |
| EvaluationFailure |
Instances
data CekValue uni fun ann Source #
Constructors
| VCon !(Some (ValueOf uni)) | |
| VDelay !(NTerm uni fun ann) !(CekValEnv uni fun ann) | |
| VLamAbs !NamedDeBruijn !(NTerm uni fun ann) !(CekValEnv uni fun ann) | |
| VBuiltin | A partial builtin application, accumulating arguments for eventual full application.
We don't need a |
Fields
| |
| VConstr !Word64 !(ArgStack uni fun ann) | |
Instances
| (PrettyUni uni, Pretty fun) ⇒ PrettyBy PrettyConfigPlc (CekValue uni fun ann) Source # | |
Defined in UntypedPlutusCore.Evaluation.Machine.Cek.Internal Methods prettyBy ∷ PrettyConfigPlc → CekValue uni fun ann → Doc ann0 Source # prettyListBy ∷ PrettyConfigPlc → [CekValue uni fun ann] → Doc ann0 Source # | |
| Show (BuiltinRuntime (CekValue uni fun ann)) Source # | |
| (GShow uni, Everywhere uni Show, Show fun, Show ann, Closed uni) ⇒ Show (CekValue uni fun ann) Source # | |
| HasConstant (CekValue uni fun ann) Source # | |
| (Closed uni, Everywhere uni ExMemoryUsage) ⇒ ExMemoryUsage (CekValue uni fun ann) Source # | |
Defined in UntypedPlutusCore.Evaluation.Machine.Cek.Internal Methods memoryUsage ∷ CekValue uni fun ann → CostRose Source # | |
| type UniOf (CekValue uni fun ann) Source # | |
data ArgStack uni fun ann Source #
A LIFO stack of CekValues, useful for recording multiple arguments which will need to
be pushed onto the context in reverse order.
Constructors
| EmptyStack | |
| ConsStack !(CekValue uni fun ann) !(ArgStack uni fun ann) |
data CekUserError Source #
Constructors
| CekOutOfExError !ExRestrictingBudget | The final overspent (i.e. negative) budget. |
| CekEvaluationFailure | Error has been called or a builtin application has failed |
Instances
type CekEvaluationException name uni fun = EvaluationException (MachineError fun) CekUserError (Term name uni fun ()) Source #
The CEK machine-specific EvaluationException.
newtype CekBudgetSpender uni fun s Source #
The CEK machine is parameterized over a spendBudget function. This makes the budgeting machinery extensible
and allows us to separate budgeting logic from evaluation logic and avoid branching on the union
of all possible budgeting state types during evaluation.
Constructors
| CekBudgetSpender | |
Fields
| |
data ExBudgetInfo cost uni fun s Source #
Runtime budgeting info.
Constructors
| ExBudgetInfo | |
Fields
| |
newtype ExBudgetMode cost uni fun Source #
A budgeting mode to execute the CEK machine in.
Constructors
| ExBudgetMode | |
Fields
| |
type CekEmitter uni fun s = DList Text → CekM uni fun s () Source #
The CEK machine is parameterized over an emitter function, similar to CekBudgetSpender.
data CekEmitterInfo uni fun s Source #
Runtime emitter info, similar to ExBudgetInfo.
Constructors
| CekEmitterInfo | |
Fields
| |
newtype EmitterMode uni fun Source #
An emitting mode to execute the CEK machine in, similar to ExBudgetMode.
Constructors
| EmitterMode | |
Fields
| |
newtype CekM uni fun s a Source #
The monad the CEK machine runs in.
Instances
| Applicative (CekM uni fun s) Source # | |
Defined in UntypedPlutusCore.Evaluation.Machine.Cek.Internal Methods pure ∷ a → CekM uni fun s a Source # (<*>) ∷ CekM uni fun s (a → b) → CekM uni fun s a → CekM uni fun s b Source # liftA2 ∷ (a → b → c) → CekM uni fun s a → CekM uni fun s b → CekM uni fun s c Source # (*>) ∷ CekM uni fun s a → CekM uni fun s b → CekM uni fun s b Source # (<*) ∷ CekM uni fun s a → CekM uni fun s b → CekM uni fun s a Source # | |
| Functor (CekM uni fun s) Source # | |
| Monad (CekM uni fun s) Source # | |
| PrimMonad (CekM uni fun s) Source # | |
| ThrowableBuiltins uni fun ⇒ MonadError (CekEvaluationException NamedDeBruijn uni fun) (CekM uni fun s) Source # | |
Defined in UntypedPlutusCore.Evaluation.Machine.Cek.Internal Methods throwError ∷ CekEvaluationException NamedDeBruijn uni fun → CekM uni fun s a Source # catchError ∷ CekM uni fun s a → (CekEvaluationException NamedDeBruijn uni fun → CekM uni fun s a) → CekM uni fun s a Source # | |
| type PrimState (CekM uni fun s) Source # | |
data ErrorWithCause err cause Source #
An error and (optionally) what caused it.
Constructors
| ErrorWithCause | |
Instances
data EvaluationError structural operational Source #
The type of errors that can occur during evaluation. There are two kinds of errors:
- Structural ones -- these are errors that are indicative of the _structure_ of the program being
wrong. For example, a free variable was encountered during evaluation, a non-function was
applied to an argument or
tailListwas applied to a non-list. - Operational ones -- these are errors that are indicative of the _logic_ of the program being
wrong. For example,
errorwas executed,tailListwas applied to an empty list or evaluation ran out of gas.
On the chain both of these are just regular failures and we don't distinguish between them there: if a script fails, it fails, it doesn't matter what the reason was. However in the tests it does matter why the failure occurred: a structural error may indicate that the test was written incorrectly while an operational error may be entirely expected.
In other words, structural errors are "runtime type errors" and operational errors are regular runtime errors. Which means that evaluating an (erased) well-typed program should never produce a structural error, only an operational one. This creates a sort of "runtime type system" for UPLC and it would be great to stick to it and enforce in tests etc, but we currently don't.
Constructors
| StructuralEvaluationError !structural | |
| OperationalEvaluationError !operational |
Instances
data ExBudgetCategory fun Source #
Constructors
| BStep StepKind | |
| BBuiltinApp fun | |
| BStartup |
Instances
Instances
type ThrowableBuiltins uni fun = (PrettyUni uni, Pretty fun, Typeable uni, Typeable fun) Source #
The set of constraints we need to be able to throw exceptions with things with built-in types and functions in them.
splitStructuralOperational ∷ Either (EvaluationException structural operational term) a → Either (ErrorWithCause structural term) (EvaluationResult a) Source #
Preserve the contents of an StructuralEvaluationError as a Left and turn an
OperationalEvaluationError into a Right EvaluationFailure (thus erasing the content of the
error in the latter case).
unsafeSplitStructuralOperational ∷ (PrettyPlc structural, PrettyPlc term, Typeable structural, Typeable term) ⇒ Either (EvaluationException structural operational term) a → EvaluationResult a Source #
Throw on a StructuralEvaluationError and turn an OperationalEvaluationError into an
EvaluationFailure (thus erasing the content of the error in the latter case).
runCekDeBruijn ∷ ThrowableBuiltins uni fun ⇒ MachineParameters CekMachineCosts fun (CekValue uni fun ann) → ExBudgetMode cost uni fun → EmitterMode uni fun → NTerm uni fun ann → (Either (CekEvaluationException NamedDeBruijn uni fun) (NTerm uni fun ()), cost, [Text]) Source #
Evaluate a term using the CEK machine and keep track of costing, logging is optional.
dischargeCekValue ∷ CekValue uni fun ann → NTerm uni fun () Source #
data Context uni fun ann Source #
The context in which the machine operates.
Morally, this is a stack of frames, but we use the "intrusive list" representation so that we can match on context and the top frame in a single, strict pattern match.
Constructors
| FrameAwaitArg !(CekValue uni fun ann) !(Context uni fun ann) | [V _] |
| FrameAwaitFunTerm !(CekValEnv uni fun ann) !(NTerm uni fun ann) !(Context uni fun ann) | [_ N] |
| FrameAwaitFunValue !(CekValue uni fun ann) !(Context uni fun ann) | [_ V] |
| FrameForce !(Context uni fun ann) |
|
| FrameConstr !(CekValEnv uni fun ann) !Word64 ![NTerm uni fun ann] !(ArgStack uni fun ann) !(Context uni fun ann) | (constr i V0 ... Vj-1 _ Nj ... Nn) |
| FrameCases !(CekValEnv uni fun ann) !(Vector (NTerm uni fun ann)) !(Context uni fun ann) | (case _ C0 .. Cn) |
| NoFrame |
type GivenCekReqs uni fun ann s = (GivenCekRuntime uni fun ann, GivenCekEmitter uni fun s, GivenCekSpender uni fun s, GivenCekSlippage, GivenCekStepCounter s, GivenCekCosts) Source #
Constraint requiring all of the machine's implicit parameters.
type GivenCekSpender uni fun s = ?cekBudgetSpender ∷ CekBudgetSpender uni fun s Source #
Implicit parameter for budget spender.
data StepCounter (n ∷ Nat) s Source #
A set of Word8 counters that is used in the CEK machine
to count steps.
type CounterSize = NumberOfStepCounters + 1 Source #
The total number of counters that we need, one extra for the total counter. See Note [Structure of the step counter]
type TotalCountIndex = NumberOfStepCounters Source #
The index at which the total step counter is kept. See Note [Structure of the step counter]
defaultSlippage ∷ Slippage Source #
The default number of slippage (in machine steps) to allow.
type NTerm uni fun = Term NamedDeBruijn uni fun Source #
The Terms that CEK can execute must have DeBruijn binders
Name is not necessary but we leave it here for simplicity and debuggability.
runCekM ∷ ∀ a cost uni fun ann. ThrowableBuiltins uni fun ⇒ MachineParameters CekMachineCosts fun (CekValue uni fun ann) → ExBudgetMode cost uni fun → EmitterMode uni fun → (∀ s. GivenCekReqs uni fun ann s ⇒ CekM uni fun s a) → (Either (CekEvaluationException NamedDeBruijn uni fun) a, cost, [Text]) Source #