Struct UserOperation

pub struct UserOperation<'a> { /* private fields */ }

A user-defined operation.

The lifetime 'a of the operation is limited by the lifetime of the underlying closure.

For safety reasons, UserOperation is in of itself not considered an Operation, but a reference of it is. This limitation may be lifted in the future when Request objects can store finalizers.

Note: When a UserOperation is passed to a non-blocking API call, it must outlive the completion of the request. This is normally enforced by the safe API, so this is only a concern if you use the unsafe API. Do not rely on MPI’s internal reference-counting here, because once UserOperation is destroyed, the closure object will be deallocated even if the MPI_Op handle is still alive due to outstanding references.

Examples

See examples/reduce.rs and examples/immediate_reduce.rs

Implementations

impl<'a> UserOperation<'a>

pub fn associative<F>(function: F) -> Self

where F: Fn(DynBuffer<'_>, DynBufferMut<'_>) + Sync + 'a,

Define an operation using a closure. The operation must be associative.

This is a more readable shorthand for the new method. Refer to new for more information.

pub fn commutative<F>(function: F) -> Self

where F: Fn(DynBuffer<'_>, DynBufferMut<'_>) + Sync + 'a,

Define an operation using a closure. The operation must be both associative and commutative.

This is a more readable shorthand for the new method. Refer to new for more information.

Examples found in repository

examples/reduce.rs (lines 23-29)

fn test_user_operations<C: Communicator>(comm: C) {
    let rank = comm.rank();
    let size = comm.size();
    let mut h = 0;
    comm.all_reduce_into(
        &(rank + 1),
        &mut h,
        &UserOperation::commutative(|x, y| {
            let x: &[Rank] = x.downcast().unwrap();
            let y: &mut [Rank] = y.downcast().unwrap();
            for (&x_i, y_i) in x.iter().zip(y) {
                *y_i += x_i;
            }
        }),
    );
    assert_eq!(h, size * (size + 1) / 2);
}

examples/immediate_reduce.rs (lines 16-22)

fn test_user_operations<C: Communicator>(comm: C) {
    let op = UserOperation::commutative(|x, y| {
        let x: &[Rank] = x.downcast().unwrap();
        let y: &mut [Rank] = y.downcast().unwrap();
        for (&x_i, y_i) in x.iter().zip(y) {
            *y_i += x_i;
        }
    });
    let rank = comm.rank();
    let size = comm.size();
    let mut c = 0;
    mpi::request::scope(|scope| {
        comm.immediate_all_reduce_into(scope, &rank, &mut c, &op)
            .wait();
    });
    assert_eq!(c, size * (size - 1) / 2);
}

pub fn new<F>(commute: bool, function: F) -> Self

where F: Fn(DynBuffer<'_>, DynBufferMut<'_>) + Sync + 'a,

Creates an associative and possibly commutative operation using a closure.

The closure receives two arguments invec and inoutvec as dynamically typed buffers. It shall set inoutvec to the value of f(invec, inoutvec), where f is a binary associative operation.

If the operation is also commutative, setting commute to true may yield performance benefits.

Note: If the closure panics, the entire program will abort.

Standard section(s)

5.9.5

pub unsafe fn from_raw<T: 'a>(op: MPI_Op, anchor: Box<T>) -> Self

Creates a UserOperation from raw parts.

Here, anchor is an arbitrary object that is stored alongside the MPI_Op. This can be used to attach finalizers to the object.

Safety

MPI_Op must not be MPI_OP_NULL

Trait Implementations

impl<'a> AsRaw for UserOperation<'a>

type Raw = *mut ompi_op_t

The raw MPI C API type

fn as_raw(&self) -> Self::Raw

The raw value

impl<'a> Debug for UserOperation<'a>

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

Formats the value using the given formatter.

impl<'a> Drop for UserOperation<'a>

fn drop(&mut self)

Executes the destructor for this type.

impl<'a, 'b> Operation for &'b UserOperation<'a>

fn is_commutative(&self) -> bool

Returns whether the operation is commutative.