[−][src]Module frame_support::weights

Primitives for transaction weighting.

Every dispatchable function is responsible for providing #[weight = $x] attribute. In this snipped, $x can be any user provided struct that implements the following traits:

WeighData: the weight amount.
ClassifyDispatch: class of the dispatch.
PaysFee: weather this weight should be translated to fee and deducted upon dispatch.

Substrate then bundles then output information of the two traits into DispatchInfo struct and provides it by implementing the GetDispatchInfo for all Call both inner and outer call types.

Substrate provides two pre-defined ways to annotate weight:

1. Fixed values

This can only be used when all 3 traits can be resolved statically. You have 3 degrees of configuration:

Define only weight, in which case ClassifyDispatch will be Normal and PaysFee will be Yes.

frame_support::decl_module! {
    pub struct Module<T: Trait> for enum Call where origin: T::Origin {
        #[weight = 1000]
        fn dispatching(origin) { unimplemented!() }
    }
}

2.1 Define weight and class, in which case PaysFee would be Yes.

frame_support::decl_module! {
    pub struct Module<T: Trait> for enum Call where origin: T::Origin {
        #[weight = (1000, DispatchClass::Operational)]
        fn dispatching(origin) { unimplemented!() }
    }
}

2.2 Define weight and PaysFee, in which case ClassifyDispatch would be Normal.

frame_support::decl_module! {
    pub struct Module<T: Trait> for enum Call where origin: T::Origin {
        #[weight = (1000, Pays::No)]
        fn dispatching(origin) { unimplemented!() }
    }
}

Define all 3 parameters.

frame_support::decl_module! {
    pub struct Module<T: Trait> for enum Call where origin: T::Origin {
        #[weight = (1000, DispatchClass::Operational, Pays::No)]
        fn dispatching(origin) { unimplemented!() }
    }
}

2. Define weights as a function of input arguments using `FunctionOf` tuple struct. This struct works

in a similar manner as above. 3 items must be provided and each can be either a fixed value or a function/closure with the same parameters list as the dispatchable function itself, wrapper in a tuple.

Using this only makes sense if you want to use a function for at least one of the elements. If all 3 are static values, providing a raw tuple is easier.

frame_support::decl_module! {
    pub struct Module<T: Trait> for enum Call where origin: T::Origin {
        #[weight = FunctionOf(
			// weight, function.
			|args: (&u32, &u64)| *args.0 as u64 + args.1,
			// class, fixed.
			DispatchClass::Operational,
			// pays fee, function.
			|args: (&u32, &u64)| if *args.0 > 1000 { Pays::Yes } else { Pays::No },
		)]
        fn dispatching(origin, a: u32, b: u64) { unimplemented!() }
    }
}

FRAME assumes a weight of 1_000_000_000_000 equals 1 second of compute on a standard machine.

Latest machine specification used to benchmark are:

Digital Ocean: ubuntu-s-2vcpu-4gb-ams3-01
2x Intel(R) Xeon(R) CPU E5-2650 v4 @ 2.20GHz
4GB RAM
Ubuntu 19.10 (GNU/Linux 5.3.0-18-generic x86_64)
rustc 1.42.0 (b8cedc004 2020-03-09)

Modules

constants	These constants are specific to FRAME, and the current implementation of its various components. For example: FRAME System, FRAME Executive, our FRAME support libraries, etc...
priority	Primitives related to priority management of Frame.

Structs

DispatchInfo	A bundle of static information collected from the `#[weight = $x]` attributes.
FunctionOf	Deprecated A struct to represent a weight which is a function of the input arguments. The given items have the following types:
IdentityFee	Implementor of `WeightToFeePolynomial` that maps one unit of weight to one unit of fee.
PostDispatchInfo	Weight information that is only available post dispatch. NOTE: This can only be used to reduce the weight or fee, not increase it.
RuntimeDbWeight	The weight of database operations that the runtime can invoke.
WeightToFeeCoefficient	One coefficient and its position in the `WeightToFeePolynomial`.

Enums

DispatchClass	A generalized group of dispatch types.
Pays	Explicit enum to denote if a transaction pays fee or not.

Traits

ClassifyDispatch	Means of classifying a dispatchable function.
GetDispatchInfo	A `Dispatchable` function (aka transaction) that can carry some static information along with it, using the `#[weight]` attribute.
PaysFee	Indicates if dispatch function should pay fees or not. If set to `Pays::No`, the block resource limits are applied, yet no fee is deducted.
WeighData	Means of weighing some particular kind of data (`T`).
WeightToFeePolynomial	A trait that describes the weight to fee calculation as polynomial.
WithPostDispatchInfo	Allows easy conversion from `DispatchError` to `DispatchErrorWithPostInfo` for dispatchables that want to return a custom a posterior weight on error.

Functions

extract_actual_weight

Extract the actual weight from a dispatch result if any or fall back to the default weight.

Type Definitions

TransactionPriority	Re-export priority as type
Weight	Numeric range of a transaction weight.
WeightToFeeCoefficients	A list of coefficients that represent one polynomial.