Trait ManagerEventSubscriber 

pub trait ManagerEventSubscriber<M: Manager> {
    // Provided methods
    fn init(&self, manager: &M) { ... }
    fn init_mut(manager: &mut M) { ... }
    fn pre_gc(&self, manager: &M) { ... }
    unsafe fn post_gc(&self, manager: &M) { ... }
    fn pre_reorder(&self, manager: &M) { ... }
    fn pre_reorder_mut(manager: &mut M) { ... }
    fn post_reorder(&self, manager: &M) { ... }
    fn post_reorder_mut(manager: &mut M) { ... }
}

Event subscriber for Manager-related events

This is intended to be implemented by data structures that can be plugged into the Manager, e.g., an ApplyCache implementation.

Use Cases

When using reference counting to implement garbage collection of dead nodes, cloning and dropping edges when inserting entries into the apply cache may cause many CPU cache misses. To circumvent this performance issue, the apply cache may store Borrowed<M::Edge>s (e.g., using the unsafe Borrowed::into_inner()). Now, the apply cache implementation has to guarantee that every edge returned by the get() method still points to a valid node. To that end, the cache may, e.g., clear itself when Self::pre_gc() is called and reject any insertion of new entries until Self::post_gc().

Safety

A use-case such as the one described above requires the pre_* methods to actually be called before any garbage collection / reordering for SAFETY. This means the struct implementing ManagerEventSubscriber must only be plugged into Manager implementations or other wrapper structures that uphold this contract, i.e., creation of the ManagerEventSubscriber implementation must be unsafe.

Additionally, we require each post_gc call to be paired with a distinct preceding pre_gc call, see below.

Provided Methods

fn init(&self, manager: &M)

Initialization

This method is called once at the very end of initializing a new manager.

fn init_mut(manager: &mut M)

Initialization

This is an alternative to Self::post_reorder() with a mutable reference to the manager as an argument. Since self may be a substructure of manager, the method cannot provide mutable references to both self and manager.

fn pre_gc(&self, manager: &M)

Prepare a garbage collection

The Manager implementation should only remove nodes (as part of a garbage collection or reordering) after calling this method. Between a pre_gc and the subsequent post_gc call, there should not be another pre_gc call.

This method may lock (parts of) self. Unlocking is then done in Self::post_gc().

Note that this method and Self::pre_reorder may both be called in case of reordering, but can also be

unsafe fn post_gc(&self, manager: &M)

Post-process a garbage collection

Safety

Each call to this method must be paired with a distinct preceding Self::pre_gc() call. All operations potentially removing nodes must happen between such a pair of method calls.

fn pre_reorder(&self, manager: &M)

Prepare a reordering operation (including any addition of levels)

The Manager implementation should only add or reorder levels after calling this method and pre_reorder_mut. Between a pre_reorder and the subsequent post_reorder call, there should not be another pre_reorder call.

fn pre_reorder_mut(manager: &mut M)

Prepare a reordering operation (including any addition of levels)

This is an alternative to Self::pre_reorder() with a mutable reference to the manager as an argument. Since self may be a substructure of manager, the method cannot provide mutable references to both self and manager.

fn post_reorder(&self, manager: &M)

Post-process a reordering operation

Each call to this method should be paired with a distinct preceding Self::pre_reorder() call. All operations reordering (or adding) levels of the decision diagram should happen between such a pair of method calls.

fn post_reorder_mut(manager: &mut M)

Post-process a reordering operation

This is an alternative to Self::post_reorder() with a mutable reference to the manager as an argument. Since self may be a substructure of manager, the method cannot provide mutable references to both self and manager.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors