Struct Managed

pub struct Managed<T: Counted> { /* private fields */ }

The Managed wrapper ensures outcomes are correctly emitted for the contained item.

Implementations

impl<T: Counted> Managed<T>

pub fn from_envelope(envelope: &ManagedEnvelope, value: T) -> Self

Creates a new managed instance with a value from a ManagedEnvelope.

The Managed instance, inherits all metadata from the passed ManagedEnvelope, like received time or scoping.

pub fn wrap<S>(&self, other: S) -> Managed<S>

where S: Counted,

Creates another Managed instance, with a new value but shared metadata.

pub fn received_at(&self) -> DateTime<Utc>

Original received timestamp.

pub fn scoping(&self) -> Scoping

Scoping information stored in this context.

pub fn split_once<F, S, U>(self, f: F) -> (Managed<S>, Managed<U>)

where F: FnOnce(T) -> (S, U), S: Counted, U: Counted,

Splits Self into two other Managed items.

The two resulting managed instances together are expected to have the same outcomes as the original instance.. Since splitting may introduce a new type of item, which some of the original quantities are transferred to, there may be new additional data categories created.

pub fn split<F, I, S>(self, f: F) -> Split<I::IntoIter, I::Item>

where F: FnOnce(T) -> I, I: IntoIterator<Item = S>, S: Counted,

Splits Self into a variable amount if individual items.

Useful when the current instance contains multiple items of the same type and must be split into individually managed items.

pub fn split_with_context<F, I, S, C>( self, f: F, ) -> (Split<I::IntoIter, I::Item>, C)

where F: FnOnce(T) -> (I, C), I: IntoIterator<Item = S>, S: Counted,

Splits Self into a variable amount if individual items.

Like Self::split but also allows returning an untracked context, a way of returning additional data when deconstructing the original item.

pub fn retain<S, I, U, E>(&mut self, select: S, retain: U)

where S: FnOnce(&mut T) -> &mut Vec<I>, I: Counted, U: FnMut(&mut I, &mut RecordKeeper<'_>) -> Result<(), E>, E: OutcomeError,

Filters individual items and emits outcomes for them if they are removed.

This is particularly useful when the managed instance is a container of individual items, which need to be processed or filtered on a case by case basis.

Examples:

struct Items {
    items: Vec<Item>,
}

fn process_items(items: &mut Managed<Items>, ctx: Context<'_>) {
    items.retain(|items| &mut items.items, |item, _| process(item, ctx));
}

fn process(item: &mut Item, ctx: Context<'_>) -> Result<(), Error> {
    todo!()
}

pub fn retain_with_context<S, C, I, U, E>(&mut self, select: S, retain: U)

where for<'a> S: FnOnce(&'a mut T) -> (&'a mut Vec<I>, &'a C), I: Counted, U: FnMut(&mut I, &C, &mut RecordKeeper<'_>) -> Result<(), E>, E: OutcomeError,

Filters individual items and emits outcomes for them if they are removed.

Like Self::retain, but it allows for an additional context extracted from the managed object passed to the retain function.

Examples:

struct Items {
    ty: String,
    items: Vec<Item>,
}

fn process_items(items: &mut Managed<Items>, ctx: Context<'_>) {
    items.retain_with_context(|items| (&mut items.items, &items.ty), |item, ty, _| process(item, ty, ctx));
}

fn process(item: &mut Item, ty: &str, ctx: Context<'_>) -> Result<(), Error> {
    todo!()
}

pub fn map<S, F>(self, f: F) -> Managed<S>

where F: FnOnce(T, &mut RecordKeeper<'_>) -> S, S: Counted,

Maps a Managed<T> to Managed<S> by applying the mapping function f.

Like Self::try_map but not fallible.

pub fn try_map<S, F, E>(self, f: F) -> Result<Managed<S>, Rejected<E::Error>>

where F: FnOnce(T, &mut RecordKeeper<'_>) -> Result<S, E>, S: Counted, E: OutcomeError,

Maps a Managed<T> to Managed<S> by applying the mapping function f.

The mapping function gets access to a RecordKeeper, to emit outcomes for partial discards.

If the mapping function returns an error, the entire (original) Self is rejected, no partial outcomes are emitted.

pub fn modify<F>(&mut self, f: F)

where F: FnOnce(&mut T, &mut RecordKeeper<'_>),

Gives mutable access to the contained value to modify it.

Like Self::try_modify but not fallible.

pub fn try_modify<F, E>(&mut self, f: F) -> Result<(), Rejected<E::Error>>

where F: FnOnce(&mut T, &mut RecordKeeper<'_>) -> Result<(), E>, E: OutcomeError,

Gives mutable access to the contained value to modify it.

The modifying function gets access to a RecordKeeper, to emit outcomes for partial discards.

If the modifying function returns an error, the entire (original) Self is rejected, no partial outcomes are emitted.

pub fn accept<F, S>(self, f: F) -> S

where F: FnOnce(T) -> S,

Accepts the item of this managed instance.

This should be called if the item has been or is about to be accepted by the upstream, which means that the responsibility for logging outcomes has been moved. This function will not log any outcomes.

Like Self::try_accept, but infallible.

pub fn try_accept<F, S, E>(self, f: F) -> Result<S, Rejected<E::Error>>

where F: FnOnce(T) -> Result<S, E>, E: OutcomeError,

Accepts the item of this managed instance.

This should be called if the item has been or is about to be accepted by the upstream.

Outcomes are only emitted when the accepting closure returns an error, which means that in the success case the responsibility for logging outcomes has been moved to the caller/upstream.

pub fn internal_error(&self, reason: &'static str) -> Rejected<()>

Rejects the entire Managed instance with an internal error.

Internal errors should be reserved for uses where logical invariants are violated. Cases which should never happen and always indicate a logical bug.

This function will panic in debug builds, but discard the item with an internal discard reason in release builds.

pub fn reject_err<E>(&self, error: E) -> Rejected<E::Error>

where E: OutcomeError,

Rejects the entire Managed instance.

Trait Implementations

impl<T: Counted> AsRef<T> for Managed<T>

fn as_ref(&self) -> &T

Converts this type into a shared reference of the (usually inferred) input type.

impl<T: Counted + Debug> Debug for Managed<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: Counted> Deref for Managed<T>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<T: Counted> Drop for Managed<T>

fn drop(&mut self)

Executes the destructor for this type.