| Safe Haskell | Safe-Inferred |
|---|---|
| Language | Haskell2010 |
UntypedPlutusCore.Evaluation.Machine.Cek.Internal
Description
The CEK machine.
Synopsis
- data EvaluationResult a
- data CekResult name uni fun
- = CekFailure (CekEvaluationException name uni fun)
- | CekSuccessConstant (Some (ValueOf uni))
- | CekSuccessNonConstant (Term name uni fun ())
- cekResultToEither ∷ CekResult name uni fun → Either (CekEvaluationException name uni fun) (Term name uni fun ())
- mapTermCekResult ∷ (Term name uni fun () → Term name' uni fun ()) → CekResult name uni fun → CekResult name' uni fun
- data CekReport cost name uni fun = CekReport {
- _cekReportResult ∷ CekResult name uni fun
- _cekReportCost ∷ cost
- _cekReportLogs ∷ [Text]
- data CekValue uni fun ann
- data DischargeResult uni fun
- = DischargeConstant (Some (ValueOf uni))
- | DischargeNonConstant (NTerm uni fun ())
- dischargeResultToTerm ∷ DischargeResult uni fun → NTerm uni fun ()
- data ArgStack uni fun ann
- data EmptyOrMultiStack uni fun ann
- = EmptyStack
- | MultiStack !(ArgStackNonEmpty uni fun ann)
- data ArgStackNonEmpty uni fun ann
- = LastStackNonEmpty !(CekValue uni fun ann)
- | ConsStackNonEmpty !(CekValue uni fun ann) !(ArgStackNonEmpty 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
- = StructuralError !structural
- | OperationalError !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 → CekReport cost NamedDeBruijn uni fun
- dischargeCekValue ∷ ∀ uni fun ann. CekValue uni fun ann → DischargeResult 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)
- | FrameAwaitFunConN !(Spine (Some (ValueOf uni))) !(Context uni fun ann)
- | FrameAwaitFunValueN !(ArgStackNonEmpty 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, GivenCekCaserBuiltin uni, 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 NumberOfStepCounters = CountConstructorsEnum (Rep StepKind)
- type CounterSize = NumberOfStepCounters + 1
- type TotalCountIndex = NumberOfStepCounters
- type Slippage = Word8
- defaultSlippage ∷ Slippage
- type NTerm uni fun = Term NamedDeBruijn uni fun
- runCekM ∷ ∀ 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 (DischargeResult uni fun)) → CekReport cost NamedDeBruijn uni fun
Documentation
data EvaluationResult a Source #
The parameterized type of results various evaluation engines return.
Constructors
| EvaluationSuccess !a | |
| EvaluationFailure |
Instances
data CekResult name uni fun Source #
The result of evaluating a term with the CEK machine.
Constructors
| CekFailure (CekEvaluationException name uni fun) | |
| CekSuccessConstant (Some (ValueOf uni)) | |
| CekSuccessNonConstant (Term name uni fun ()) |
cekResultToEither ∷ CekResult name uni fun → Either (CekEvaluationException name uni fun) (Term name uni fun ()) Source #
mapTermCekResult ∷ (Term name uni fun () → Term name' uni fun ()) → CekResult name uni fun → CekResult name' uni fun Source #
data CekReport cost name uni fun Source #
All info produced by a CEK machine run.
Constructors
| CekReport | |
Fields
| |
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 !(EmptyOrMultiStack 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 DischargeResult uni fun Source #
The result of dischargeCekValue.
Constructors
| DischargeConstant (Some (ValueOf uni)) | |
| DischargeNonConstant (NTerm uni fun ()) |
Instances
| (PrettyUni uni, Pretty fun) ⇒ PrettyBy PrettyConfigPlc (DischargeResult uni fun) Source # | |
Defined in UntypedPlutusCore.Evaluation.Machine.Cek.Internal Methods prettyBy ∷ PrettyConfigPlc → DischargeResult uni fun → Doc ann Source # prettyListBy ∷ PrettyConfigPlc → [DischargeResult uni fun] → Doc ann Source # | |
| (GShow uni, Everywhere uni Show, Show fun, Closed uni) ⇒ Show (DischargeResult uni fun) Source # | |
| (GEq uni, Everywhere uni Eq, Eq fun, Closed uni) ⇒ Eq (DischargeResult uni fun) Source # | |
Defined in UntypedPlutusCore.Evaluation.Machine.Cek.Internal Methods (==) ∷ DischargeResult uni fun → DischargeResult uni fun → Bool Source # (/=) ∷ DischargeResult uni fun → DischargeResult uni fun → Bool Source # | |
dischargeResultToTerm ∷ DischargeResult uni fun → NTerm uni fun () Source #
data ArgStack uni fun ann Source #
A LIFO stack of CekValues, used to record multiple arguments that need to be pushed
onto the context in reverse order. Currently used by FrameConstr for collecting the
elements of a Constr as it is cheap to prepend new elements in ArgStack.
data EmptyOrMultiStack uni fun ann Source #
An alternative version of ArgStack that uses ArgNonEmptyStack when non-empty.
Used in VConstr. Once all evaluated elements of Constr is collecting to ArgStack
in FrameConstr, the collected elements gets reversed and put into VConstr as
EmptyOrMultiStack. VConstr using EmptyOrMultiStack is more efficient than ArgStack when casing,
since FrameAwaitFunValueN can be dispatched with a single pattern match.
Constructors
| EmptyStack | |
| MultiStack !(ArgStackNonEmpty uni fun ann) |
Instances
| (GShow uni, Everywhere uni Show, Show fun, Show ann, Closed uni) ⇒ Show (EmptyOrMultiStack uni fun ann) Source # | |
data ArgStackNonEmpty uni fun ann Source #
A non-empty variant of ArgStack, used in FrameAwaitFunValueN to store arguments
that will be applied to a term. More efficient than ArgStack, since this saves one
evaluation cycle by ensuring there is no NilStack.
Constructors
| LastStackNonEmpty !(CekValue uni fun ann) | |
| ConsStackNonEmpty !(CekValue uni fun ann) !(ArgStackNonEmpty uni fun ann) |
Instances
| (GShow uni, Everywhere uni Show, Show fun, Show ann, Closed uni) ⇒ Show (ArgStackNonEmpty uni fun ann) Source # | |
data CekUserError Source #
Constructors
| CekCaseBuiltinError Text |
|
| 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
| StructuralError !structural | |
| OperationalError !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 StructuralError as a Left and turn an
OperationalError 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 StructuralError and turn an OperationalError 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 → CekReport cost NamedDeBruijn uni fun Source #
Evaluate a term using the CEK machine and keep track of costing, logging is optional.
dischargeCekValue ∷ ∀ uni fun ann. CekValue uni fun ann → DischargeResult 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] |
| FrameAwaitFunConN !(Spine (Some (ValueOf uni))) !(Context uni fun ann) | [_ V] |
| FrameAwaitFunValueN !(ArgStackNonEmpty uni fun ann) !(Context uni fun ann) | [_ V1 .. Vn] |
| 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, GivenCekCaserBuiltin uni, 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 NumberOfStepCounters = CountConstructorsEnum (Rep StepKind) Source #
The number of step counters that we need, should be the same as the number of constructors
of StepKind.
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 ∷ ∀ 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 (DischargeResult uni fun)) → CekReport cost NamedDeBruijn uni fun Source #