| Safe Haskell | Safe-Inferred |
|---|---|
| Language | Haskell2010 |
UntypedPlutusCore.Evaluation.Machine.SteppableCek
Description
The API to the Steppable CEK machine. Provides the same interface to original CEK machine.
Synopsis
- runCek ∷ ThrowableBuiltins uni fun ⇒ MachineParameters CekMachineCosts fun (CekValue uni fun ann) → ExBudgetMode cost uni fun → EmitterMode uni fun → Term Name uni fun ann → (Either (CekEvaluationException Name uni fun) (Term Name uni fun ()), cost, [Text])
- 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])
- runCekNoEmit ∷ ThrowableBuiltins uni fun ⇒ MachineParameters CekMachineCosts fun (CekValue uni fun ann) → ExBudgetMode cost uni fun → Term Name uni fun ann → (Either (CekEvaluationException Name uni fun) (Term Name uni fun ()), cost)
- evaluateCek ∷ ThrowableBuiltins uni fun ⇒ EmitterMode uni fun → MachineParameters CekMachineCosts fun (CekValue uni fun ann) → Term Name uni fun ann → (Either (CekEvaluationException Name uni fun) (Term Name uni fun ()), [Text])
- evaluateCekNoEmit ∷ ThrowableBuiltins uni fun ⇒ MachineParameters CekMachineCosts fun (CekValue uni fun ann) → Term Name uni fun ann → Either (CekEvaluationException Name uni fun) (Term Name uni fun ())
- data EvaluationResult a
- 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
- data CekUserError
- data ErrorWithCause err cause = ErrorWithCause {}
- type CekEvaluationException name uni fun = EvaluationException (MachineError fun) CekUserError (Term name uni fun ())
- data EvaluationError structural operational
- = StructuralEvaluationError !structural
- | OperationalEvaluationError !operational
- data ExBudgetCategory fun
- = BStep StepKind
- | BBuiltinApp fun
- | BStartup
- newtype CekBudgetSpender uni fun s = CekBudgetSpender {
- unCekBudgetSpender ∷ ExBudgetCategory fun → ExBudget → CekM uni fun s ()
- newtype ExBudgetMode cost uni fun = ExBudgetMode {
- unExBudgetMode ∷ ∀ s. ST s (ExBudgetInfo cost uni fun s)
- data StepKind
- newtype CekExTally fun = CekExTally (MonoidalHashMap (ExBudgetCategory fun) ExBudget)
- newtype CountingSt = CountingSt ExBudget
- data TallyingSt fun = TallyingSt (CekExTally fun) ExBudget
- newtype RestrictingSt = RestrictingSt ExRestrictingBudget
- type CekMachineCosts = CekMachineCostsBase Identity
- counting ∷ ExBudgetMode CountingSt uni fun
- tallying ∷ Hashable fun ⇒ ExBudgetMode (TallyingSt fun) uni fun
- restricting ∷ ThrowableBuiltins uni fun ⇒ ExRestrictingBudget → ExBudgetMode RestrictingSt uni fun
- restrictingEnormous ∷ ThrowableBuiltins uni fun ⇒ ExBudgetMode RestrictingSt uni fun
- enormousBudget ∷ ExRestrictingBudget
- noEmitter ∷ EmitterMode uni fun
- logEmitter ∷ EmitterMode uni fun
- logWithTimeEmitter ∷ EmitterMode uni fun
- logWithBudgetEmitter ∷ EmitterMode uni fun
- data CekValue uni fun ann
- readKnownCek ∷ (ThrowableBuiltins uni fun, ReadKnown (Term Name uni fun ()) a) ⇒ MachineParameters CekMachineCosts fun (CekValue uni fun ann) → Term Name uni fun ann → Either (CekEvaluationException Name uni fun) a
- class Eq a ⇒ Hashable a
- type ThrowableBuiltins uni fun = (PrettyUni uni, Pretty fun, Typeable uni, Typeable fun)
Running the machine
runCek ∷ ThrowableBuiltins uni fun ⇒ MachineParameters CekMachineCosts fun (CekValue uni fun ann) → ExBudgetMode cost uni fun → EmitterMode uni fun → Term Name uni fun ann → (Either (CekEvaluationException Name uni fun) (Term Name uni fun ()), cost, [Text]) Source #
Evaluate a term using the Steppable CEK machine with logging enabled and keep track of costing. A wrapper around the internal runCek to debruijn input and undebruijn output. *THIS FUNCTION IS PARTIAL if the input term contains free variables*
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 #
runCekNoEmit ∷ ThrowableBuiltins uni fun ⇒ MachineParameters CekMachineCosts fun (CekValue uni fun ann) → ExBudgetMode cost uni fun → Term Name uni fun ann → (Either (CekEvaluationException Name uni fun) (Term Name uni fun ()), cost) Source #
Evaluate a term using the Steppable CEK machine with logging disabled and keep track of costing. *THIS FUNCTION IS PARTIAL if the input term contains free variables*
evaluateCek ∷ ThrowableBuiltins uni fun ⇒ EmitterMode uni fun → MachineParameters CekMachineCosts fun (CekValue uni fun ann) → Term Name uni fun ann → (Either (CekEvaluationException Name uni fun) (Term Name uni fun ()), [Text]) Source #
Evaluate a term using the Steppable CEK machine with logging enabled. *THIS FUNCTION IS PARTIAL if the input term contains free variables*
evaluateCekNoEmit ∷ ThrowableBuiltins uni fun ⇒ MachineParameters CekMachineCosts fun (CekValue uni fun ann) → Term Name uni fun ann → Either (CekEvaluationException Name uni fun) (Term Name uni fun ()) Source #
Evaluate a term using the Steppable CEK machine with logging disabled. *THIS FUNCTION IS PARTIAL if the input term contains free variables*
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
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).
Errors
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
data ErrorWithCause err cause Source #
An error and (optionally) what caused it.
Constructors
| ErrorWithCause | |
Instances
type CekEvaluationException name uni fun = EvaluationException (MachineError fun) CekUserError (Term name uni fun ()) Source #
The CEK machine-specific EvaluationException.
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
Costing
data ExBudgetCategory fun Source #
Constructors
| BStep StepKind | |
| BBuiltinApp fun | |
| BStartup |
Instances
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
| |
newtype ExBudgetMode cost uni fun Source #
A budgeting mode to execute the CEK machine in.
Constructors
| ExBudgetMode | |
Fields
| |
Instances
newtype CekExTally fun Source #
For a detailed report on what costs how much + the same overall budget that Counting gives.
The (derived) Monoid instance of CekExTally is the main piece of the machinery.
Constructors
| CekExTally (MonoidalHashMap (ExBudgetCategory fun) ExBudget) |
Instances
newtype CountingSt Source #
Constructors
| CountingSt ExBudget |
Instances
| Monoid CountingSt Source # | |
Defined in UntypedPlutusCore.Evaluation.Machine.Cek.ExBudgetMode Methods mappend ∷ CountingSt → CountingSt → CountingSt Source # mconcat ∷ [CountingSt] → CountingSt Source # | |
| Semigroup CountingSt Source # | |
Defined in UntypedPlutusCore.Evaluation.Machine.Cek.ExBudgetMode Methods (<>) ∷ CountingSt → CountingSt → CountingSt Source # sconcat ∷ NonEmpty CountingSt → CountingSt Source # stimes ∷ Integral b ⇒ b → CountingSt → CountingSt Source # | |
| Show CountingSt Source # | |
| NFData CountingSt Source # | |
Defined in UntypedPlutusCore.Evaluation.Machine.Cek.ExBudgetMode Methods rnf ∷ CountingSt → () Source # | |
| Eq CountingSt Source # | |
| Pretty CountingSt Source # | |
| PrettyBy config CountingSt Source # | |
Defined in UntypedPlutusCore.Evaluation.Machine.Cek.ExBudgetMode Methods prettyBy ∷ config → CountingSt → Doc ann Source # prettyListBy ∷ config → [CountingSt] → Doc ann Source # | |
data TallyingSt fun Source #
Constructors
| TallyingSt (CekExTally fun) ExBudget |
Instances
newtype RestrictingSt Source #
Constructors
| RestrictingSt ExRestrictingBudget |
Instances
type CekMachineCosts = CekMachineCostsBase Identity Source #
Costs for evaluating AST nodes. Times should be specified in picoseconds, memory sizes in bytes.
Costing modes
counting ∷ ExBudgetMode CountingSt uni fun Source #
For calculating the cost of execution.
tallying ∷ Hashable fun ⇒ ExBudgetMode (TallyingSt fun) uni fun Source #
For a detailed report on what costs how much + the same overall budget that Counting gives.
restricting ∷ ThrowableBuiltins uni fun ⇒ ExRestrictingBudget → ExBudgetMode RestrictingSt uni fun Source #
For execution, to avoid overruns.
restrictingEnormous ∷ ThrowableBuiltins uni fun ⇒ ExBudgetMode RestrictingSt uni fun Source #
restricting instantiated at enormousBudget.
enormousBudget ∷ ExRestrictingBudget Source #
When we want to just evaluate the program we use the Restricting mode with an enormous
budget, so that evaluation costs of on-chain budgeting are reflected accurately in benchmarks.
Emitter modes
noEmitter ∷ EmitterMode uni fun Source #
No emitter.
logEmitter ∷ EmitterMode uni fun Source #
Emits log only.
logWithTimeEmitter ∷ EmitterMode uni fun Source #
Emits log with timestamp.
logWithBudgetEmitter ∷ EmitterMode uni fun Source #
Emits log with the budget.
Misc
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 # | |
readKnownCek ∷ (ThrowableBuiltins uni fun, ReadKnown (Term Name uni fun ()) a) ⇒ MachineParameters CekMachineCosts fun (CekValue uni fun ann) → Term Name uni fun ann → Either (CekEvaluationException Name uni fun) a Source #
Unlift a value using the Steppable CEK machine. *THIS FUNCTION IS PARTIAL if the input term contains free variables*
class Eq a ⇒ Hashable a Source #
The class of types that can be converted to a hash value.
Minimal implementation: hashWithSalt.
Hashable is intended exclusively for use in in-memory data structures.
.
Hashable does not have a fixed standard.
This allows it to improve over time.
.
Because it does not have a fixed standard, different computers or computers on different versions of the code will observe different hash values.
As such, Hashable is not recommended for use other than in-memory datastructures.
Specifically, Hashable is not intended for network use or in applications which persist hashed values.
For stable hashing use named hashes: sha256, crc32, xxhash etc.
If you are looking for Hashable instance in time package,
check time-compat