| Safe Haskell | Safe-Inferred |
|---|---|
| Language | Haskell2010 |
UntypedPlutusCore.Evaluation.Machine.Cek
Description
The API to the 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 -> CekReport cost Name uni fun
- 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
- runCekNoEmit :: ThrowableBuiltins uni fun => MachineParameters CekMachineCosts fun (CekValue uni fun ann) -> ExBudgetMode cost uni fun -> Term Name uni fun ann -> (Text]
- = DischargeConstant (Some (ValueOf uni))
- | DischargeNonConstant (NTerm uni 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 -> CekReport cost Name uni fun #
Evaluate a term using the 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 -> CekReport cost NamedDeBruijn uni fun #
Evaluate a term using the CEK machine and keep track of costing, logging is optional.
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) #
Evaluate a term using the 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 -> (Text]) #
Evaluate a term using the 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 ()) #
Evaluate a term using the CEK machine with logging disabled. *THIS FUNCTION IS PARTIAL if the input term contains free variables*
data EvaluationResult a #
The parameterized type of results various evaluation engines return.
Constructors
| EvaluationSuccess !a | |
| EvaluationFailure |
Instances
splitStructuralOperational :: Either (EvaluationException structural operational term) a -> Either (ErrorWithCause structural term) (EvaluationResult a) #
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 #
Throw on a StructuralError and turn an OperationalError into an
EvaluationFailure (thus erasing the content of the error in the latter case).
Errors
data CekUserError #
Constructors
| CekCaseBuiltinError Text)) :+: (C1 ('MetaCons "CekOutOfExError" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 ExRestrictingBudget)) :+: C1 ('MetaCons "CekEvaluationFailure" 'PrefixI 'False) (U1 :: Type -> Type))) |
data ErrorWithCause err cause #
An error and (optionally) what caused it.
Constructors
| ErrorWithCause | |
Instances
type CekEvaluationException name uni fun = EvaluationException (MachineError fun) CekUserError (Term name uni fun ()) #
The CEK machine-specific EvaluationException.
data EvaluationError structural operational #
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
| Bifoldable EvaluationError # | |
Defined in PlutusCore.Evaluation.Error Methods bifold :: Monoid m => EvaluationError m m -> m # bifoldMap :: Monoid m => (a -> m) -> (b -> m) -> EvaluationError a b -> m # bifoldr :: (a -> c -> c) -> (b -> c -> c) -> c -> EvaluationError a b -> c # bifoldl :: (c -> a -> c) -> (c -> b -> c) -> c -> EvaluationError a b -> c # | |
| Bifunctor EvaluationError # | |
Defined in PlutusCore.Evaluation.Error Methods bimap :: (a -> b) -> (c -> d) -> EvaluationError a c -> EvaluationError b d # first :: (a -> b) -> EvaluationError a c -> EvaluationError b c # second :: (b -> c) -> EvaluationError a b -> EvaluationError a c # | |
| Bitraversable EvaluationError # | |
Defined in PlutusCore.Evaluation.Error Methods bitraverse :: Applicative f => (a -> f c) -> (b -> f d) -> EvaluationError a b -> f (EvaluationError c d) # | |
| (HasPrettyDefaults config ~ 'True, PrettyBy config structural, Pretty operational) => PrettyBy config (EvaluationError structural operational) # | |
Defined in PlutusCore.Evaluation.Error Methods prettyBy :: config -> EvaluationError structural operational -> Doc ann # prettyListBy :: config -> [EvaluationError structural operational] -> Doc ann # | |
| Functor (EvaluationError structural) # | |
Defined in PlutusCore.Evaluation.Error Methods fmap :: (a -> b) -> EvaluationError structural a -> EvaluationError structural b # (<$) :: a -> EvaluationError structural b -> EvaluationError structural a # | |
| Generic (EvaluationError structural operational) # | |
Defined in PlutusCore.Evaluation.Error Associated Types type Rep (EvaluationError structural operational) :: Type -> Type # Methods from :: EvaluationError structural operational -> Rep (EvaluationError structural operational) x # to :: Rep (EvaluationError structural operational) x -> EvaluationError structural operational # | |
| (Show structural, Show operational) => Show (EvaluationError structural operational) # | |
Defined in PlutusCore.Evaluation.Error Methods showsPrec :: Int -> EvaluationError structural operational -> ShowS # show :: EvaluationError structural operational -> String # showList :: [EvaluationError structural operational] -> ShowS # | |
| (NFData structural, NFData operational) => NFData (EvaluationError structural operational) # | |
Defined in PlutusCore.Evaluation.Error Methods rnf :: EvaluationError structural operational -> () # | |
| (Eq structural, Eq operational) => Eq (EvaluationError structural operational) # | |
Defined in PlutusCore.Evaluation.Error Methods (==) :: EvaluationError structural operational -> EvaluationError structural operational -> Bool # (/=) :: EvaluationError structural operational -> EvaluationError structural operational -> Bool # | |
| (Pretty structural, Pretty operational) => Pretty (EvaluationError structural operational) # | |
Defined in PlutusCore.Evaluation.Error Methods pretty :: EvaluationError structural operational -> Doc ann # prettyList :: [EvaluationError structural operational] -> Doc ann # | |
| ThrowableBuiltins uni fun => MonadError (CekEvaluationException NamedDeBruijn uni fun) (CekM uni fun s) # | |
Defined in UntypedPlutusCore.Evaluation.Machine.Cek.Internal Methods throwError :: CekEvaluationException NamedDeBruijn uni fun -> CekM uni fun s a # catchError :: CekM uni fun s a -> (CekEvaluationException NamedDeBruijn uni fun -> CekM uni fun s a) -> CekM uni fun s a # | |
| type Rep (EvaluationError structural operational) # | |
Defined in PlutusCore.Evaluation.Error type Rep (EvaluationError structural operational) = D1 ('MetaData "EvaluationError" "PlutusCore.Evaluation.Error" "plutus-core-1.60.0.0-inplace" 'False) (C1 ('MetaCons "StructuralError" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 structural)) :+: C1 ('MetaCons "OperationalError" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 operational))) | |
Costing
data ExBudgetCategory fun #
Constructors
| BStep StepKind | |
| BBuiltinApp fun | |
| BStartup |
Instances
newtype CekBudgetSpender uni fun s #
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 #
A budgeting mode to execute the CEK machine in.
Constructors
| ExBudgetMode | |
Fields
| |
Instances
newtype CekExTally fun #
For a detailed report on what costs how much + the same overall budget that Counting gives.
The (derived) MonoidalHashMap (ExBudgetCategory fun) ExBudget))))
newtype CountingSt #
Constructors
| CountingSt ExBudget |
Instances
| Monoid CountingSt # | |
Defined in UntypedPlutusCore.Evaluation.Machine.Cek.ExBudgetMode Methods mempty :: CountingSt # mappend :: CountingSt -> CountingSt -> CountingSt # mconcat :: [CountingSt] -> CountingSt # | |
| Semigroup CountingSt # | |
Defined in UntypedPlutusCore.Evaluation.Machine.Cek.ExBudgetMode Methods (<>) :: CountingSt -> CountingSt -> CountingSt # sconcat :: NonEmpty CountingSt -> CountingSt # stimes :: Integral b => b -> CountingSt -> CountingSt # | |
| Show CountingSt # | |
Defined in UntypedPlutusCore.Evaluation.Machine.Cek.ExBudgetMode Methods showsPrec :: Int -> CountingSt -> ShowS # show :: CountingSt -> String # showList :: [CountingSt] -> ShowS # | |
| NFData CountingSt # | |
Defined in UntypedPlutusCore.Evaluation.Machine.Cek.ExBudgetMode Methods rnf :: CountingSt -> () # | |
| Eq CountingSt # | |
| Pretty CountingSt # | |
| PrettyBy config CountingSt # | |
Defined in UntypedPlutusCore.Evaluation.Machine.Cek.ExBudgetMode Methods prettyBy :: config -> CountingSt -> Doc ann # prettyListBy :: config -> [CountingSt] -> Doc ann # | |
data TallyingSt fun #
Constructors
| TallyingSt (CekExTally fun) ExBudget |
Instances
newtype RestrictingSt #
Constructors
| RestrictingSt ExRestrictingBudget |
Instances
type CekMachineCosts = CekMachineCostsBase Identity #
Costs for evaluating AST nodes. Times should be specified in picoseconds, memory sizes in bytes.
Costing modes
monoidalBudgeting :: Monoid cost => (ExBudgetCategory fun -> ExBudget -> cost) -> ExBudgetMode cost uni fun #
Construct an ExBudgetMode out of a function returning a value of the budgeting state type.
The value then gets added to the current state via (<>).
counting :: ExBudgetMode CountingSt uni fun #
For calculating the cost of execution.
tallying :: Hashable fun => ExBudgetMode (TallyingSt fun) uni fun #
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 #
For execution, to avoid overruns.
restrictingLarge :: ThrowableBuiltins uni fun => ExBudgetMode RestrictingSt uni fun #
restricting instantiated at largeBudget.
restrictingEnormous :: ThrowableBuiltins uni fun => ExBudgetMode RestrictingSt uni fun #
restricting instantiated at enormousBudget.
enormousBudget :: ExRestrictingBudget #
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 #
No emitter.
logEmitter :: EmitterMode uni fun #
Emits log only.
logWithTimeEmitter :: EmitterMode uni fun #
Emits log with timestamp.
logWithBudgetEmitter :: EmitterMode uni fun #
Emits log with the budget.
logWithCallTraceEmitter :: EmitterMode uni fun #
Emits log and, when script evaluation fails, call trace.
This requires script to be compiled with `PlutusTx.Plugin:profile-all` turned on because this relies
on compiler-generated trace calls that notifies entrance and exit of a function call. These traces
that mark entrance and exit are ordinary traces like "-> rob:Example.hs:3:1-3:15" and "<-
bob:Example.hs:1:1-1:13" with "->" and "<-" prefixies, where "bob" and "rob" is the name
of the function with source span. If regular script with no entrance/exit marker is given, this
emitter will behave identically to logEmitter.
When script evaluation fails, this emitter will give call trace of the functions that led to the
evaluation failure. This is useful for pin-pointing specific area of the codebase that caused
failure when debugging a script. When script evaluation passes, every trace message generated by
`profile-all` flag will be removed, and this emitter will behave identically to logEmitter.
Misc
data BuiltinsRuntime fun val #
A data wrapper around a function returning the BuiltinRuntime of a built-in function.
In order for lookups to be efficient the BuiltinRuntimes need to be cached, i.e. pulled out
of the function statically. See makeBuiltinMeaning for how we achieve that.
Constructors
| BuiltinsRuntime | |
Fields
| |
Instances
| (Text] Logs emitted during evaluation. |
cekResultToEither :: CekResult name uni fun -> Either (CekEvaluationException name uni fun) (Term name uni fun ()) #
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) # | |
Defined in UntypedPlutusCore.Evaluation.Machine.Cek.Internal Methods prettyBy :: PrettyConfigPlc -> CekValue uni fun ann -> Doc ann0 # prettyListBy :: PrettyConfigPlc -> [CekValue uni fun ann] -> Doc ann0 # | |
| Show (BuiltinRuntime (CekValue uni fun ann)) # | |
| (GShow uni, Everywhere uni Show, Show fun, Show ann, Closed uni) => Show (CekValue uni fun ann) # | |
| HasConstant (CekValue uni fun ann) # | |
| (Closed uni, Everywhere uni ExMemoryUsage) => ExMemoryUsage (CekValue uni fun ann) # | |
Defined in UntypedPlutusCore.Evaluation.Machine.Cek.Internal Methods memoryUsage :: CekValue uni fun ann -> CostRose # | |
| type UniOf (CekValue uni fun ann) # | |
data DischargeResult uni fun #
The result of dischargeCekValue.
Constructors
| DischargeConstant (Some (ValueOf uni)) | |
| DischargeNonConstant (NTerm uni fun ()) |
Instances
| (PrettyUni uni, Pretty fun) => PrettyBy PrettyConfigPlc (DischargeResult uni fun) # | |
Defined in UntypedPlutusCore.Evaluation.Machine.Cek.Internal Methods prettyBy :: PrettyConfigPlc -> DischargeResult uni fun -> Doc ann # prettyListBy :: PrettyConfigPlc -> [DischargeResult uni fun] -> Doc ann # | |
| (GShow uni, Everywhere uni Show, Show fun, Closed uni) => Show (DischargeResult uni fun) # | |
Defined in UntypedPlutusCore.Evaluation.Machine.Cek.Internal Methods showsPrec :: Int -> DischargeResult uni fun -> ShowS # show :: DischargeResult uni fun -> String # showList :: [DischargeResult uni fun] -> ShowS # | |
| (GEq uni, Everywhere uni Eq, Eq fun, Closed uni) => Eq (DischargeResult uni fun) # | |
Defined in UntypedPlutusCore.Evaluation.Machine.Cek.Internal Methods (==) :: DischargeResult uni fun -> DischargeResult uni fun -> Bool # (/=) :: DischargeResult uni fun -> DischargeResult uni fun -> Bool # | |
dischargeResultToTerm :: DischargeResult uni fun -> NTerm uni fun () #
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 #
Unlift a value using the CEK machine. *THIS FUNCTION IS PARTIAL if the input term contains free variables*
class 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
Instances
| Hashable Key | |
Defined in Data.Aeson.Key Methods | |