Struct frame_system::limits::BlockWeightsBuilder

pub struct BlockWeightsBuilder { /* private fields */ }

An opinionated builder for Weights object.

Implementations

impl BlockWeightsBuilder

pub fn base_block(self, base_block: Weight) -> Self

Set base block weight.

Examples found in repository

src/limits.rs (line 306)

	pub fn simple_max(block_weight: Weight) -> Self {
		Self::builder()
			.base_block(Weight::zero())
			.for_class(DispatchClass::all(), |weights| {
				weights.base_extrinsic = Weight::zero();
			})
			.for_class(DispatchClass::non_mandatory(), |weights| {
				weights.max_total = block_weight.into();
			})
			.build()
			.expect("We only specify max_total and leave base values as defaults; qed")
	}

pub fn avg_block_initialization(self, init_cost: Perbill) -> Self

Average block initialization weight cost.

This value is used to derive maximal allowed extrinsic weight for each class, based on the allowance.

This is to make sure that extrinsics don’t stay forever in the pool, because they could seamingly fit the block (since they are below max_block), but the cost of calling on_initialize always prevents them from being included.

Examples found in repository

src/limits.rs (line 333)

	pub fn with_sensible_defaults(expected_block_weight: Weight, normal_ratio: Perbill) -> Self {
		let normal_weight = normal_ratio * expected_block_weight;
		Self::builder()
			.for_class(DispatchClass::Normal, |weights| {
				weights.max_total = normal_weight.into();
			})
			.for_class(DispatchClass::Operational, |weights| {
				weights.max_total = expected_block_weight.into();
				weights.reserved = (expected_block_weight - normal_weight).into();
			})
			.avg_block_initialization(Perbill::from_percent(10))
			.build()
			.expect("Sensible defaults are tested to be valid; qed")
	}

pub fn for_class(
    self,
    class: impl OneOrMany<DispatchClass>,
    action: impl Fn(&mut WeightsPerClass)
) -> Self

Set parameters for particular class.

Note: None values of max_extrinsic will be overwritten in build in case avg_block_initialization rate is set to a non-zero value.

Examples found in repository

src/limits.rs (lines 307-309)

	pub fn simple_max(block_weight: Weight) -> Self {
		Self::builder()
			.base_block(Weight::zero())
			.for_class(DispatchClass::all(), |weights| {
				weights.base_extrinsic = Weight::zero();
			})
			.for_class(DispatchClass::non_mandatory(), |weights| {
				weights.max_total = block_weight.into();
			})
			.build()
			.expect("We only specify max_total and leave base values as defaults; qed")
	}

	/// Create a sensible default weights system given only expected maximal block weight and the
	/// ratio that `Normal` extrinsics should occupy.
	///
	/// Assumptions:
	///  - Average block initialization is assumed to be `10%`.
	///  - `Operational` transactions have reserved allowance (`1.0 - normal_ratio`)
	pub fn with_sensible_defaults(expected_block_weight: Weight, normal_ratio: Perbill) -> Self {
		let normal_weight = normal_ratio * expected_block_weight;
		Self::builder()
			.for_class(DispatchClass::Normal, |weights| {
				weights.max_total = normal_weight.into();
			})
			.for_class(DispatchClass::Operational, |weights| {
				weights.max_total = expected_block_weight.into();
				weights.reserved = (expected_block_weight - normal_weight).into();
			})
			.avg_block_initialization(Perbill::from_percent(10))
			.build()
			.expect("Sensible defaults are tested to be valid; qed")
	}

pub fn build(self) -> ValidationResult

Construct the BlockWeights object.

Examples found in repository

src/limits.rs (line 313)

	pub fn simple_max(block_weight: Weight) -> Self {
		Self::builder()
			.base_block(Weight::zero())
			.for_class(DispatchClass::all(), |weights| {
				weights.base_extrinsic = Weight::zero();
			})
			.for_class(DispatchClass::non_mandatory(), |weights| {
				weights.max_total = block_weight.into();
			})
			.build()
			.expect("We only specify max_total and leave base values as defaults; qed")
	}

	/// Create a sensible default weights system given only expected maximal block weight and the
	/// ratio that `Normal` extrinsics should occupy.
	///
	/// Assumptions:
	///  - Average block initialization is assumed to be `10%`.
	///  - `Operational` transactions have reserved allowance (`1.0 - normal_ratio`)
	pub fn with_sensible_defaults(expected_block_weight: Weight, normal_ratio: Perbill) -> Self {
		let normal_weight = normal_ratio * expected_block_weight;
		Self::builder()
			.for_class(DispatchClass::Normal, |weights| {
				weights.max_total = normal_weight.into();
			})
			.for_class(DispatchClass::Operational, |weights| {
				weights.max_total = expected_block_weight.into();
				weights.reserved = (expected_block_weight - normal_weight).into();
			})
			.avg_block_initialization(Perbill::from_percent(10))
			.build()
			.expect("Sensible defaults are tested to be valid; qed")
	}

	/// Start constructing new `BlockWeights` object.
	///
	/// By default all kinds except of `Mandatory` extrinsics are disallowed.
	pub fn builder() -> BlockWeightsBuilder {
		BlockWeightsBuilder {
			weights: BlockWeights {
				base_block: constants::BlockExecutionWeight::get(),
				max_block: Weight::zero(),
				per_class: PerDispatchClass::new(|class| {
					let initial =
						if class == DispatchClass::Mandatory { None } else { Some(Weight::zero()) };
					WeightsPerClass {
						base_extrinsic: constants::ExtrinsicBaseWeight::get(),
						max_extrinsic: None,
						max_total: initial,
						reserved: initial,
					}
				}),
			},
			init_cost: None,
		}
	}
}

/// An opinionated builder for `Weights` object.
pub struct BlockWeightsBuilder {
	weights: BlockWeights,
	init_cost: Option<Perbill>,
}

impl BlockWeightsBuilder {
	/// Set base block weight.
	pub fn base_block(mut self, base_block: Weight) -> Self {
		self.weights.base_block = base_block;
		self
	}

	/// Average block initialization weight cost.
	///
	/// This value is used to derive maximal allowed extrinsic weight for each
	/// class, based on the allowance.
	///
	/// This is to make sure that extrinsics don't stay forever in the pool,
	/// because they could seamingly fit the block (since they are below `max_block`),
	/// but the cost of calling `on_initialize` always prevents them from being included.
	pub fn avg_block_initialization(mut self, init_cost: Perbill) -> Self {
		self.init_cost = Some(init_cost);
		self
	}

	/// Set parameters for particular class.
	///
	/// Note: `None` values of `max_extrinsic` will be overwritten in `build` in case
	/// `avg_block_initialization` rate is set to a non-zero value.
	pub fn for_class(
		mut self,
		class: impl OneOrMany<DispatchClass>,
		action: impl Fn(&mut WeightsPerClass),
	) -> Self {
		for class in class.into_iter() {
			action(self.weights.per_class.get_mut(class));
		}
		self
	}

	/// Construct the `BlockWeights` object.
	pub fn build(self) -> ValidationResult {
		// compute max extrinsic size
		let Self { mut weights, init_cost } = self;

		// compute max block size.
		for class in DispatchClass::all() {
			weights.max_block = match weights.per_class.get(*class).max_total {
				Some(max) => max.max(weights.max_block),
				_ => weights.max_block,
			};
		}
		// compute max size of single extrinsic
		if let Some(init_weight) = init_cost.map(|rate| rate * weights.max_block) {
			for class in DispatchClass::all() {
				let per_class = weights.per_class.get_mut(*class);
				if per_class.max_extrinsic.is_none() && init_cost.is_some() {
					per_class.max_extrinsic = per_class
						.max_total
						.map(|x| x.saturating_sub(init_weight))
						.map(|x| x.saturating_sub(per_class.base_extrinsic));
				}
			}
		}

		// Validate the result
		weights.validate()
	}

	/// Construct the `BlockWeights` object or panic if it's invalid.
	///
	/// This is a convenience method to be called whenever you construct a runtime.
	pub fn build_or_panic(self) -> BlockWeights {
		self.build().expect(
			"Builder finished with `build_or_panic`; The panic is expected if runtime weights are not correct"
		)
	}

pub fn build_or_panic(self) -> BlockWeights

Construct the BlockWeights object or panic if it’s invalid.

This is a convenience method to be called whenever you construct a runtime.