| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
UntypedPlutusCore.Evaluation.Machine.Cek
Description
The API to the CEK machine.
Synopsis
- runCek :: (uni `Everywhere` ExMemoryUsage, Ix fun, PrettyUni uni fun) => MachineParameters CekMachineCosts CekValue uni fun -> ExBudgetMode cost uni fun -> EmitterMode uni fun -> Term Name uni fun () -> (Either (CekEvaluationException Name uni fun) (Term Name uni fun ()), cost, [Text])
- runCekDeBruijn :: (uni `Everywhere` ExMemoryUsage, Ix fun, PrettyUni uni fun) => MachineParameters CekMachineCosts CekValue uni fun -> ExBudgetMode cost uni fun -> EmitterMode uni fun -> Term NamedDeBruijn uni fun () -> (Either (CekEvaluationException NamedDeBruijn uni fun) (Term NamedDeBruijn uni fun ()), cost, [Text])
- runCekNoEmit :: (uni `Everywhere` ExMemoryUsage, Ix fun, PrettyUni uni fun) => MachineParameters CekMachineCosts CekValue uni fun -> ExBudgetMode cost uni fun -> Term Name uni fun () -> (Either (CekEvaluationException Name uni fun) (Term Name uni fun ()), cost)
- unsafeRunCekNoEmit :: (GShow uni, Typeable uni, Closed uni, uni `EverywhereAll` '[ExMemoryUsage, PrettyConst], Ix fun, Pretty fun, Typeable fun) => MachineParameters CekMachineCosts CekValue uni fun -> ExBudgetMode cost uni fun -> Term Name uni fun () -> (EvaluationResult (Term Name uni fun ()), cost)
- evaluateCek :: (uni `Everywhere` ExMemoryUsage, Ix fun, PrettyUni uni fun) => EmitterMode uni fun -> MachineParameters CekMachineCosts CekValue uni fun -> Term Name uni fun () -> (Either (CekEvaluationException Name uni fun) (Term Name uni fun ()), [Text])
- evaluateCekNoEmit :: (uni `Everywhere` ExMemoryUsage, Ix fun, PrettyUni uni fun) => MachineParameters CekMachineCosts CekValue uni fun -> Term Name uni fun () -> Either (CekEvaluationException Name uni fun) (Term Name uni fun ())
- unsafeEvaluateCek :: (GShow uni, Typeable uni, Closed uni, uni `EverywhereAll` '[ExMemoryUsage, PrettyConst], Ix fun, Pretty fun, Typeable fun) => EmitterMode uni fun -> MachineParameters CekMachineCosts CekValue uni fun -> Term Name uni fun () -> (EvaluationResult (Term Name uni fun ()), [Text])
- unsafeEvaluateCekNoEmit :: (GShow uni, Typeable uni, Closed uni, uni `EverywhereAll` '[ExMemoryUsage, PrettyConst], Ix fun, Pretty fun, Typeable fun) => MachineParameters CekMachineCosts CekValue uni fun -> Term Name uni fun () -> EvaluationResult (Term Name uni fun ())
- data EvaluationResult a
- extractEvaluationResult :: Either (EvaluationException user internal term) a -> Either (ErrorWithCause internal term) (EvaluationResult a)
- unsafeExtractEvaluationResult :: (PrettyPlc internal, PrettyPlc term, Typeable internal, Typeable term) => Either (EvaluationException user internal term) a -> EvaluationResult a
- data CekUserError
- data ErrorWithCause err cause = ErrorWithCause {}
- type CekEvaluationException name uni fun = EvaluationException CekUserError (MachineError fun) (Term name uni fun ())
- data EvaluationError user internal
- = InternalEvaluationError internal
- | UserEvaluationError user
- 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 :: forall 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
- data CekMachineCosts
- counting :: ExBudgetMode CountingSt uni fun
- tallying :: (Eq fun, Hashable fun) => ExBudgetMode (TallyingSt fun) uni fun
- restricting :: forall uni fun. PrettyUni uni fun => ExRestrictingBudget -> ExBudgetMode RestrictingSt uni fun
- restrictingEnormous :: PrettyUni 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
- = VCon !(Some (ValueOf uni))
- | VDelay (Term NamedDeBruijn uni fun ()) !(CekValEnv uni fun)
- | VLamAbs NamedDeBruijn (Term NamedDeBruijn uni fun ()) !(CekValEnv uni fun)
- | VBuiltin !fun (Term NamedDeBruijn uni fun ()) (CekValEnv uni fun) !(BuiltinRuntime (CekValue uni fun))
- readKnownCek :: (uni `Everywhere` ExMemoryUsage, ReadKnown (Term Name uni fun ()) a, Ix fun, PrettyUni uni fun) => MachineParameters CekMachineCosts CekValue uni fun -> Term Name uni fun () -> Either (CekEvaluationException Name uni fun) a
- class Hashable a
- type PrettyUni uni fun = (GShow uni, Closed uni, Pretty fun, Typeable uni, Typeable fun, Everywhere uni PrettyConst)
Running the machine
runCek :: (uni `Everywhere` ExMemoryUsage, Ix fun, PrettyUni uni fun) => MachineParameters CekMachineCosts CekValue uni fun -> ExBudgetMode cost uni fun -> EmitterMode uni fun -> Term Name uni fun () -> (Either (CekEvaluationException Name uni fun) (Term Name uni fun ()), cost, [Text]) Source #
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 :: (uni `Everywhere` ExMemoryUsage, Ix fun, PrettyUni uni fun) => MachineParameters CekMachineCosts CekValue uni fun -> ExBudgetMode cost uni fun -> EmitterMode uni fun -> Term NamedDeBruijn uni fun () -> (Either (CekEvaluationException NamedDeBruijn uni fun) (Term NamedDeBruijn uni fun ()), cost, [Text]) Source #
Evaluate a term using the CEK machine and keep track of costing, logging is optional.
runCekNoEmit :: (uni `Everywhere` ExMemoryUsage, Ix fun, PrettyUni uni fun) => MachineParameters CekMachineCosts CekValue uni fun -> ExBudgetMode cost uni fun -> Term Name uni fun () -> (Either (CekEvaluationException Name uni fun) (Term Name uni fun ()), cost) Source #
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*
unsafeRunCekNoEmit :: (GShow uni, Typeable uni, Closed uni, uni `EverywhereAll` '[ExMemoryUsage, PrettyConst], Ix fun, Pretty fun, Typeable fun) => MachineParameters CekMachineCosts CekValue uni fun -> ExBudgetMode cost uni fun -> Term Name uni fun () -> (EvaluationResult (Term Name uni fun ()), cost) Source #
Unsafely evaluate a term using the CEK machine with logging disabled and keep track of costing.
May throw a CekMachineException.
*THIS FUNCTION IS PARTIAL if the input term contains free variables*
evaluateCek :: (uni `Everywhere` ExMemoryUsage, Ix fun, PrettyUni uni fun) => EmitterMode uni fun -> MachineParameters CekMachineCosts CekValue uni fun -> Term Name uni fun () -> (Either (CekEvaluationException Name uni fun) (Term Name uni fun ()), [Text]) Source #
Evaluate a term using the CEK machine with logging enabled. *THIS FUNCTION IS PARTIAL if the input term contains free variables*
evaluateCekNoEmit :: (uni `Everywhere` ExMemoryUsage, Ix fun, PrettyUni uni fun) => MachineParameters CekMachineCosts CekValue uni fun -> Term Name uni fun () -> Either (CekEvaluationException Name uni fun) (Term Name uni fun ()) Source #
Evaluate a term using the CEK machine with logging disabled. *THIS FUNCTION IS PARTIAL if the input term contains free variables*
unsafeEvaluateCek :: (GShow uni, Typeable uni, Closed uni, uni `EverywhereAll` '[ExMemoryUsage, PrettyConst], Ix fun, Pretty fun, Typeable fun) => EmitterMode uni fun -> MachineParameters CekMachineCosts CekValue uni fun -> Term Name uni fun () -> (EvaluationResult (Term Name uni fun ()), [Text]) Source #
Evaluate a term using the CEK machine with logging enabled. May throw a CekMachineException.
*THIS FUNCTION IS PARTIAL if the input term contains free variables*
unsafeEvaluateCekNoEmit :: (GShow uni, Typeable uni, Closed uni, uni `EverywhereAll` '[ExMemoryUsage, PrettyConst], Ix fun, Pretty fun, Typeable fun) => MachineParameters CekMachineCosts CekValue uni fun -> Term Name uni fun () -> EvaluationResult (Term Name uni fun ()) Source #
Evaluate a term using the CEK machine with logging disabled. May throw a CekMachineException.
*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
extractEvaluationResult :: Either (EvaluationException user internal term) a -> Either (ErrorWithCause internal term) (EvaluationResult a) Source #
Turn any UserEvaluationError into an EvaluationFailure.
unsafeExtractEvaluationResult :: (PrettyPlc internal, PrettyPlc term, Typeable internal, Typeable term) => Either (EvaluationException user internal term) a -> EvaluationResult a Source #
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 CekUserError (MachineError fun) (Term name uni fun ()) Source #
The CEK machine-specific EvaluationException.
data EvaluationError user internal Source #
The type of errors (all of them) which can occur during evaluation (some are used-caused, some are internal).
Constructors
| InternalEvaluationError internal | Indicates bugs. |
| UserEvaluationError user | Indicates user errors. |
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
data TallyingSt fun Source #
Constructors
| TallyingSt (CekExTally fun) ExBudget |
Instances
newtype RestrictingSt Source #
Constructors
| RestrictingSt ExRestrictingBudget |
Instances
data CekMachineCosts Source #
Costs for evaluating AST nodes. Times should be specified in picoseconds, memory sizes in bytes.
Instances
Costing modes
counting :: ExBudgetMode CountingSt uni fun Source #
For calculating the cost of execution.
tallying :: (Eq fun, 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 :: forall uni fun. PrettyUni uni fun => ExRestrictingBudget -> ExBudgetMode RestrictingSt uni fun Source #
For execution, to avoid overruns.
restrictingEnormous :: PrettyUni 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 Source #
Constructors
| VCon !(Some (ValueOf uni)) | |
| VDelay (Term NamedDeBruijn uni fun ()) !(CekValEnv uni fun) | |
| VLamAbs NamedDeBruijn (Term NamedDeBruijn uni fun ()) !(CekValEnv uni fun) | |
| VBuiltin !fun (Term NamedDeBruijn uni fun ()) (CekValEnv uni fun) !(BuiltinRuntime (CekValue uni fun)) |
Instances
| (Closed uni, GShow uni, Everywhere uni PrettyConst, Pretty fun) => PrettyBy PrettyConfigPlc (CekValue uni fun) Source # | |
Defined in UntypedPlutusCore.Evaluation.Machine.Cek.Internal Methods prettyBy :: PrettyConfigPlc -> CekValue uni fun -> Doc ann # prettyListBy :: PrettyConfigPlc -> [CekValue uni fun] -> Doc ann # | |
| Show (BuiltinRuntime (CekValue uni fun)) Source # | |
| (Everywhere uni Show, GShow uni, Closed uni, Show fun) => Show (CekValue uni fun) Source # | |
| HasConstant (CekValue uni fun) Source # | |
Defined in UntypedPlutusCore.Evaluation.Machine.Cek.Internal Methods asConstant :: AsUnliftingError err => Maybe cause -> CekValue uni fun -> Either (ErrorWithCause err cause) (Some (ValueOf (UniOf (CekValue uni fun)))) Source # fromConstant :: Some (ValueOf (UniOf (CekValue uni fun))) -> CekValue uni fun Source # | |
| type UniOf (CekValue uni fun) Source # | |
readKnownCek :: (uni `Everywhere` ExMemoryUsage, ReadKnown (Term Name uni fun ()) a, Ix fun, PrettyUni uni fun) => MachineParameters CekMachineCosts CekValue uni fun -> Term Name uni fun () -> Either (CekEvaluationException Name uni fun) a Source #
Unlift a value using the CEK machine. *THIS FUNCTION IS PARTIAL if the input term contains free variables*
Instances
type PrettyUni uni fun = (GShow uni, Closed uni, Pretty fun, Typeable uni, Typeable fun, Everywhere uni PrettyConst) Source #
The set of constraints we need to be able to print things in universes, which we need in order to throw exceptions.