Struct Request

pub struct Request<'a, S: Scope<'a> = StaticScope> { /* private fields */ }

A request object for a non-blocking operation registered with a Scope of lifetime 'a

The Scope is needed to ensure that all buffers associated request will outlive the request itself, even if the destructor of the request fails to run.

Panics

Panics if the request object is dropped. To prevent this, call wait, wait_without_status, or test. Alternatively, wrap the request inside a WaitGuard or CancelGuard.

Examples

See examples/immediate.rs

Standard section(s)

3.7.1

Implementations

impl<'a, S: Scope<'a>> Request<'a, S>

pub unsafe fn from_raw(request: MPI_Request, scope: S) -> Self

Construct a request object from the raw MPI type.

Requirements

• The request is a valid, active request. It must not be MPI_REQUEST_NULL.
• The request must not be persistent.
• All buffers associated with the request must outlive 'a.
• The request must not be registered with the given scope.

Panics

Persistent request

Safety

• request must be a live MPI object.
• request must not be used after calling from_raw.
• Any buffers owned by request must live longer than scope.

pub unsafe fn into_raw(self) -> (MPI_Request, S)

Unregister the request object from its scope and deconstruct it into its raw parts.

This is unsafe because the request may outlive its associated buffers.

Safety

• The returned MPI_Request must be completed within the lifetime of the returned scope.

pub fn wait(self) -> Status

Wait for an operation to finish.

Will block execution of the calling thread until the associated operation has finished.

Examples

See examples/immediate.rs

Standard section(s)

3.7.3

Examples found in repository

examples/immediate_all_to_all.rs (line 18)

fn main() {
    let universe = mpi::initialize().unwrap();
    let world = universe.world();
    let rank = world.rank();
    let size = world.size();

    let u = vec![rank; size as usize];
    let mut v = vec![0; size as usize];

    mpi::request::scope(|scope| {
        world
            .immediate_all_to_all_into(scope, &u[..], &mut v[..])
            .wait();
    });

    println!("u: {:?}", u);
    println!("v: {:?}", v);

    assert!(v.into_iter().zip(0..size).all(|(i, j)| i == j));
}

examples/immediate_reduce.rs (line 28)

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);
}

#[cfg(not(feature = "user-operations"))]
fn test_user_operations<C: Communicator>(_: C) {}

#[cfg(not(all(msmpi, target_arch = "x86")))]
unsafe extern "C" fn unsafe_add(
    invec: *mut c_void,
    inoutvec: *mut c_void,
    len: *mut c_int,
    _datatype: *mut MPI_Datatype,
) {
    use std::slice;

    let x: &[Rank] = slice::from_raw_parts(invec as *const Rank, *len as usize);
    let y: &mut [Rank] = slice::from_raw_parts_mut(inoutvec as *mut Rank, *len as usize);
    for (&x_i, y_i) in x.iter().zip(y) {
        *y_i += x_i;
    }
}

#[cfg(all(msmpi, target_arch = "x86"))]
unsafe extern "stdcall" fn unsafe_add(
    invec: *mut c_void,
    inoutvec: *mut c_void,
    len: *mut c_int,
    _datatype: *mut MPI_Datatype,
) {
    use std::slice;

    let x: &[Rank] = slice::from_raw_parts(invec as *const Rank, *len as usize);
    let y: &mut [Rank] = slice::from_raw_parts_mut(inoutvec as *mut Rank, *len as usize);
    for (&x_i, y_i) in x.iter().zip(y) {
        *y_i += x_i;
    }
}

fn main() {
    let universe = mpi::initialize().unwrap();
    let world = universe.world();
    let rank = world.rank();
    let size = world.size();
    let root_rank = 0;

    if rank == root_rank {
        let mut sum: Rank = 0;
        mpi::request::scope(|scope| {
            world
                .process_at_rank(root_rank)
                .immediate_reduce_into_root(scope, &rank, &mut sum, SystemOperation::sum())
                .wait();
        });
        assert_eq!(sum, size * (size - 1) / 2);
    } else {
        mpi::request::scope(|scope| {
            world
                .process_at_rank(root_rank)
                .immediate_reduce_into(scope, &rank, SystemOperation::sum())
                .wait();
        });
    }

    let mut max: Rank = -1;

    mpi::request::scope(|scope| {
        world
            .immediate_all_reduce_into(scope, &rank, &mut max, SystemOperation::max())
            .wait();
    });
    assert_eq!(max, size - 1);

    let a = (0..size).collect::<Vec<_>>();
    let mut b: Rank = 0;

    mpi::request::scope(|scope| {
        world
            .immediate_reduce_scatter_block_into(scope, &a[..], &mut b, SystemOperation::product())
            .wait();
    });
    assert_eq!(b, rank.wrapping_pow(size as u32));

    test_user_operations(universe.world());

    let mut d = 0;
    let op = unsafe { UnsafeUserOperation::commutative(unsafe_add) };
    mpi::request::scope(|scope| {
        world
            .immediate_all_reduce_into(scope, &rank, &mut d, &op)
            .wait();
    });
    assert_eq!(d, size * (size - 1) / 2);
}

examples/immediate_scan.rs (line 21)

fn main() {
    let universe = mpi::initialize().unwrap();
    let world = universe.world();
    let rank = world.rank();

    let mut x = 0;
    mpi::request::scope(|scope| {
        world
            .immediate_scan_into(scope, &rank, &mut x, SystemOperation::sum())
            .wait();
    });
    assert_eq!(x, (rank * (rank + 1)) / 2);

    let y = rank + 1;
    let mut z = 0;
    mpi::request::scope(|scope| {
        world
            .immediate_exclusive_scan_into(scope, &y, &mut z, SystemOperation::product())
            .wait();
    });
    if rank > 0 {
        assert_eq!(z, fac(y - 1));
    }
}

examples/immediate_scatter.rs (line 20)

fn main() {
    let universe = mpi::initialize().unwrap();
    let world = universe.world();
    let rank = world.rank();
    let size = world.size();
    let root_rank = 0;
    let root_process = world.process_at_rank(root_rank);

    let mut x = 0 as Rank;
    if rank == root_rank {
        let v = (0..size).collect::<Vec<_>>();
        mpi::request::scope(|scope| {
            let req = root_process.immediate_scatter_into_root(scope, &v[..], &mut x);
            req.wait();
        });
    } else {
        mpi::request::scope(|scope| {
            let req = root_process.immediate_scatter_into(scope, &mut x);
            req.wait();
        });
    }
    assert_eq!(x, rank);
}

examples/ready_send.rs (line 31)

fn main() {
    let universe = mpi::initialize().unwrap();
    let world = universe.world();
    let size = world.size();
    let rank = world.rank();

    if rank > 0 {
        let msg = rank as u8;
        world.barrier();
        world.process_at_rank(0).ready_send(&msg);
    } else {
        let mut v = vec![0u8; (size - 1) as usize];
        mpi::request::scope(|scope| {
            let reqs = v
                .iter_mut()
                .zip(1..)
                .map(|(x, i)| {
                    world
                        .process_at_rank(i as Rank)
                        .immediate_receive_into(scope, x)
                })
                .collect::<Vec<_>>();
            world.barrier();
            for req in reqs {
                req.wait();
            }
        });
        println!("Got message: {:?}", v);
        assert!(v.iter().zip(1..).all(|(x, i)| i == *x as usize));
    }
}

examples/immediate_all_gather_varcount.rs (line 32)

fn main() {
    let universe = mpi::initialize().unwrap();
    let world = universe.world();

    let rank = world.rank();
    let size = world.size();

    let msg: Vec<_> = (0..rank).collect();

    let counts: Vec<Count> = (0..size).collect();
    let displs: Vec<Count> = counts
        .iter()
        .scan(0, |acc, &x| {
            let tmp = *acc;
            *acc += x;
            Some(tmp)
        })
        .collect();

    let mut buf = vec![0; (size * (size - 1) / 2) as usize];
    {
        let mut partition = PartitionMut::new(&mut buf[..], counts, &displs[..]);
        mpi::request::scope(|scope| {
            let req = world.immediate_all_gather_varcount_into(scope, &msg[..], &mut partition);
            req.wait();
        });
    }

    assert!(buf
        .iter()
        .zip((0..size).flat_map(|r| (0..r)))
        .all(|(&i, j)| i == j));
    println!("Process {} got message {:?}", rank, buf);
}

Additional examples can be found in:

• examples/wait_any.rs
• examples/immediate_broadcast.rs
• examples/immediate_scatter_varcount.rs
• examples/immediate_gather_varcount.rs
• examples/immediate_barrier.rs
• examples/immediate_all_gather.rs
• examples/immediate.rs
• examples/immediate_gather.rs

pub fn wait_without_status(self)

Wait for an operation to finish, but don’t bother retrieving the Status information.

Will block execution of the calling thread until the associated operation has finished.

Standard section(s)

3.7.3

pub fn test(self) -> Result<Status, Self>

Test whether an operation has finished.

Errors

If the operation has finished, Status is returned. Otherwise returns the unfinished Request.

Panics

Persistent request

Examples

See examples/immediate.rs

Standard section(s)

3.7.3

Examples found in repository

examples/immediate.rs (line 20)

fn main() {
    let universe = mpi::initialize().unwrap();
    let world = universe.world();

    let x = std::f32::consts::PI;
    let mut y: f32 = 0.0;

    mpi::request::scope(|scope| {
        let mut sreq = world.this_process().immediate_send(scope, &x);
        let rreq = world.any_process().immediate_receive_into(scope, &mut y);
        rreq.wait();
        loop {
            match sreq.test() {
                Ok(_) => {
                    break;
                }
                Err(req) => {
                    sreq = req;
                }
            }
        }
    });
    assert_eq!(x, y);

    y = 0.0;
    mpi::request::scope(|scope| {
        let _rreq = WaitGuard::from(world.any_process().immediate_receive_into(scope, &mut y));
        let _sreq = WaitGuard::from(world.this_process().immediate_ready_send(scope, &x));
    });
    assert_eq!(x, y);

    assert!(world.any_process().immediate_probe().is_none());
    assert!(world.any_process().immediate_matched_probe().is_none());

    y = 0.0;
    mpi::request::scope(|scope| {
        let _sreq: WaitGuard<_> = world
            .this_process()
            .immediate_synchronous_send(scope, &x)
            .into();
        let preq = world.any_process().immediate_matched_probe();
        assert!(preq.is_some());
        let (msg, _) = preq.unwrap();
        let _rreq: WaitGuard<_> = msg.immediate_matched_receive_into(scope, &mut y).into();
    });
    assert_eq!(x, y);

    let future = world.any_process().immediate_receive();
    world.this_process().send(&x);
    let (msg, _) = future.get();
    assert_eq!(x, msg);

    let future = world.any_process().immediate_receive();
    let res = future.r#try();
    assert!(res.is_err());
    let mut future = res.err().unwrap();
    world.this_process().send(&x);
    loop {
        match future.r#try() {
            Ok((msg, _)) => {
                assert_eq!(x, msg);
                break;
            }
            Err(f) => {
                future = f;
            }
        }
    }

    mpi::request::scope(|scope| {
        let sreq = world.this_process().immediate_send(scope, &x);
        sreq.cancel();
        sreq.wait();

        let _sreq = CancelGuard::from(world.this_process().immediate_receive_into(scope, &mut y));
    });
}

pub fn cancel(&self)

Initiate cancellation of the request.

The MPI implementation is not guaranteed to fulfill this operation. It may not even be valid for certain types of requests. In the future, the MPI forum may deprecate cancellation of sends entirely.

Examples

See examples/immediate.rs

Standard section(s)

3.8.4

Examples found in repository

examples/immediate.rs (line 79)

fn main() {
    let universe = mpi::initialize().unwrap();
    let world = universe.world();

    let x = std::f32::consts::PI;
    let mut y: f32 = 0.0;

    mpi::request::scope(|scope| {
        let mut sreq = world.this_process().immediate_send(scope, &x);
        let rreq = world.any_process().immediate_receive_into(scope, &mut y);
        rreq.wait();
        loop {
            match sreq.test() {
                Ok(_) => {
                    break;
                }
                Err(req) => {
                    sreq = req;
                }
            }
        }
    });
    assert_eq!(x, y);

    y = 0.0;
    mpi::request::scope(|scope| {
        let _rreq = WaitGuard::from(world.any_process().immediate_receive_into(scope, &mut y));
        let _sreq = WaitGuard::from(world.this_process().immediate_ready_send(scope, &x));
    });
    assert_eq!(x, y);

    assert!(world.any_process().immediate_probe().is_none());
    assert!(world.any_process().immediate_matched_probe().is_none());

    y = 0.0;
    mpi::request::scope(|scope| {
        let _sreq: WaitGuard<_> = world
            .this_process()
            .immediate_synchronous_send(scope, &x)
            .into();
        let preq = world.any_process().immediate_matched_probe();
        assert!(preq.is_some());
        let (msg, _) = preq.unwrap();
        let _rreq: WaitGuard<_> = msg.immediate_matched_receive_into(scope, &mut y).into();
    });
    assert_eq!(x, y);

    let future = world.any_process().immediate_receive();
    world.this_process().send(&x);
    let (msg, _) = future.get();
    assert_eq!(x, msg);

    let future = world.any_process().immediate_receive();
    let res = future.r#try();
    assert!(res.is_err());
    let mut future = res.err().unwrap();
    world.this_process().send(&x);
    loop {
        match future.r#try() {
            Ok((msg, _)) => {
                assert_eq!(x, msg);
                break;
            }
            Err(f) => {
                future = f;
            }
        }
    }

    mpi::request::scope(|scope| {
        let sreq = world.this_process().immediate_send(scope, &x);
        sreq.cancel();
        sreq.wait();

        let _sreq = CancelGuard::from(world.this_process().immediate_receive_into(scope, &mut y));
    });
}

pub fn shrink_scope_to<'b, S2>(self, scope: S2) -> Request<'b, S2>

where S2: Scope<'b>, 'a: 'b,

Reduce the scope of a request.

Trait Implementations

impl<'a, S: Scope<'a>> AsRaw for Request<'a, S>

type Raw = *mut ompi_request_t

The raw MPI C API type

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

The raw value

impl<'a, S: Debug + Scope<'a>> Debug for Request<'a, S>

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

Formats the value using the given formatter.

impl<'a, S: Scope<'a>> Drop for Request<'a, S>

fn drop(&mut self)

Executes the destructor for this type.

impl<'a, S: Scope<'a>> From<Request<'a, S>> for CancelGuard<'a, S>

fn from(req: Request<'a, S>) -> Self

Converts to this type from the input type.

impl<'a, S: Scope<'a>> From<Request<'a, S>> for WaitGuard<'a, S>

fn from(req: Request<'a, S>) -> Self

Converts to this type from the input type.

impl<'a, S: Scope<'a>> From<WaitGuard<'a, S>> for Request<'a, S>

fn from(guard: WaitGuard<'a, S>) -> Self

Converts to this type from the input type.