Skip to main content

MutFieldGetter

The provider-side form of HasFieldMut: wired field access that can mutate.

info

Generated machinery​

You are not expected to name MutFieldGetter in wiring. A getter component whose method takes &mut self accepts any provider of it through WithProvider, and UseField implements it, so the wiring entry is WithField<Tag> as for a read. The one case for implementing it yourself is a provider whose mutable access no existing provider expresses.

Overview​

In Context-Generic Programming (CGP), FieldGetter is field access in provider shape, so that a context, the type the method runs on, which supplies the values it needs as its fields, can choose by wiring which field answers a getter. MutFieldGetter is the same with mutation: it hands back a &mut rather than a &, for a getter whose method takes &mut self. The four field-access traits divide on two axes:

you bound againstyou wire
readHasFieldFieldGetter
writeHasFieldMutMutFieldGetter

Definition​

MutFieldGetter<Context, Tag> extends FieldGetter with one method that returns a mutable borrow:

pub trait MutFieldGetter<Context, Tag>: FieldGetter<Context, Tag> {
fn get_field_mut(context: &mut Context, tag: PhantomData<Tag>) -> &mut Self::Value;
}

It stands to FieldGetter as HasFieldMut stands to HasField: a supertrait extension, with the field's type inherited from the supertrait's Value. Self is the provider and Context is the type being mutated, passed as &mut Context.

Usage​

It is not in the prelude; import it from cgp::core::field::traits. A getter whose method takes &mut self and returns &mut T is wired the same way as a read, with WithField<Tag> from cgp::core::field::impls:

delegate_components! {
App {
CounterGetterComponent: WithField<Symbol!("request_count")>,
}
}

A bare UseField<Tag> entry works too, through the impl #[cgp_getter] emits for UseField directly. Implementing the trait yourself means implementing FieldGetter as well, its supertrait.

Examples​

A mutable getter named counter_mut that reads the request_count field:

use cgp::prelude::*;
use cgp::core::field::impls::WithField;

#[cgp_getter(CounterGetter)]
pub trait HasCounter {
fn counter_mut(&mut self) -> &mut u64;
}

#[derive(HasField)]
pub struct App {
pub request_count: u64,
}

delegate_components! {
App {
CounterGetterComponent: WithField<Symbol!("request_count")>,
}
}

check_components! {
App {
CounterGetterComponent,
}
}

pub fn demo() {
let mut app = App { request_count: 0 };
*app.counter_mut() += 1;
assert_eq!(app.request_count, 1);
}

UseField implements MutFieldGetter for any context whose field has HasFieldMut, which the derive always emits. App is an environmental context, and the getter is self-targeted.

When to use it​

Wire mutable access only when a context must choose which field is mutated, which is rarer than the read case and rarer still than mutation generally.

  • An #[implicit] argument reaches a field of the implementation's own context, mutably too, with no provider involved.
  • HasFieldMut is the bound for an implementation that requires mutable access rather than having it wired.
  • FieldGetter is the form for read-only wired access, the common case.

Under the hood​

For a one-method getter whose method takes &mut self, #[cgp_getter] bounds its WithProvider impl on MutFieldGetter instead of FieldGetter. cargo cgp expand on the example shows:

impl<__Context__, __Provider__> CounterGetter<__Context__> for WithProvider<__Provider__>
where
__Provider__: MutFieldGetter<__Context__, CounterGetterComponent, Value = u64>,
{
fn counter_mut(__context__: &mut __Context__) -> &mut u64 {
__Provider__::get_field_mut(
__context__,
::core::marker::PhantomData::<CounterGetterComponent>,
)
}
}

UseField<Tag> implements MutFieldGetter for every tag it is asked under, through the context's HasFieldMut<Tag>, and UseFieldRef implements it through AsMut. UseContext has no MutFieldGetter impl, so a mutable getter cannot be wired through WithContext.

Common Mistakes​

Self is the provider, not the context. The context is the first type parameter, and arrives as &mut Context rather than as &mut self.

Implementing it means implementing FieldGetter. It is a supertrait, so the read half is not optional.

The 'static bound behind DerefMut can bite. A context behind a smart pointer to borrowed data satisfies the read and not the write; see HasFieldMut.

  • FieldGetter: the supertrait, where wired access is explained in full.
  • HasFieldMut: the consumer side you bound against.
  • UseField and WithField: the provider that implements both halves, and its WithProvider alias.
  • #[cgp_getter]: the macro whose mutable getters take this trait.

The ideas behind it:

Source​


An AI agent wrote this page using the CGP knowledge base. Its content was verified against the library's source. See How AI is used in this project.