Trait Communicator

pub trait Communicator: AsRaw<Raw = MPI_Comm> {
    // Provided methods
    fn size(&self) -> Rank { ... }
    fn rank(&self) -> Rank { ... }
    fn process_at_rank(&self, r: Rank) -> Process<'_, Self>
       where Self: Sized { ... }
    fn any_process(&self) -> AnyProcess<'_, Self>
       where Self: Sized { ... }
    fn this_process(&self) -> Process<'_, Self>
       where Self: Sized { ... }
    fn compare<C>(&self, other: &C) -> CommunicatorRelation
       where C: Communicator + ?Sized { ... }
    fn duplicate(&self) -> UserCommunicator { ... }
    fn split_by_color(&self, color: Color) -> Option<UserCommunicator> { ... }
    fn split_by_color_with_key(
        &self,
        color: Color,
        key: Key,
    ) -> Option<UserCommunicator> { ... }
    fn split_shared(&self, key: c_int) -> UserCommunicator { ... }
    fn split_by_subgroup_collective<G>(
        &self,
        group: &G,
    ) -> Option<UserCommunicator>
       where G: Group + ?Sized { ... }
    fn split_by_subgroup<G>(&self, group: &G) -> Option<UserCommunicator>
       where G: Group + ?Sized { ... }
    fn split_by_subgroup_with_tag<G>(
        &self,
        group: &G,
        tag: Tag,
    ) -> Option<UserCommunicator>
       where G: Group + ?Sized { ... }
    fn group(&self) -> UserGroup { ... }
    fn abort(&self, errorcode: c_int) -> ! { ... }
    fn set_name(&self, name: &str) { ... }
    fn get_name(&self) -> String { ... }
    fn create_cartesian_communicator(
        &self,
        dims: &[Count],
        periods: &[bool],
        reorder: bool,
    ) -> Option<CartesianCommunicator> { ... }
    fn cartesian_map(&self, dims: &[Count], periods: &[bool]) -> Option<Rank> { ... }
    fn pack_size<Dt>(&self, incount: Count, datatype: &Dt) -> Count
       where Dt: Datatype { ... }
    fn pack<Buf>(&self, inbuf: &Buf) -> Vec<u8> 
       where Buf: ?Sized + Buffer { ... }
    fn pack_into<Buf>(
        &self,
        inbuf: &Buf,
        outbuf: &mut [u8],
        position: Count,
    ) -> Count
       where Buf: ?Sized + Buffer { ... }
    unsafe fn unpack_into<Buf>(
        &self,
        inbuf: &[u8],
        outbuf: &mut Buf,
        position: Count,
    ) -> Count
       where Buf: ?Sized + BufferMut { ... }
}

Communicators are contexts for communication

Provided Methods

fn size(&self) -> Rank

Number of processes in this communicator

Examples

See examples/simple.rs

Standard section(s)

6.4.1

Examples found in repository

examples/simple.rs (line 12)

fn main() {
    let universe = mpi::initialize().unwrap();
    let world = universe.world();
    println!(
        "Hello parallel world from process {} of {}!",
        world.rank(),
        world.size()
    );
}

examples/cartesian_map.rs (line 11)

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

    let comm = universe.world();

    let new_rank = comm.cartesian_map(&[2, comm.size() / 4], &[false, false]);

    println!("{} -> {:?}", comm.rank(), new_rank);
}

examples/all_gather_bool.rs (line 11)

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

    let rank = world.rank();
    let count = world.size() as usize;

    let mut a = vec![false; count];
    world.all_gather_into(&(rank % 2 == 0), &mut a[..]);

    let answer: Vec<_> = (0..count).map(|i| i % 2 == 0).collect();

    assert_eq!(answer, a);
}

examples/all_to_all.rs (line 10)

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];

    world.all_to_all_into(&u[..], &mut v[..]);

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

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

examples/scatter.rs (line 11)

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<_>>();
        root_process.scatter_into_root(&v[..], &mut x);
    } else {
        root_process.scatter_into(&mut x);
    }
    assert_eq!(x, rank);
}

examples/immediate_all_to_all.rs (line 10)

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

Additional examples can be found in:

• examples/reduce.rs
• examples/immediate_reduce.rs
• examples/immediate_scatter.rs
• examples/barrier.rs
• examples/all_gather_varcount.rs
• examples/ready_send.rs
• examples/immediate_all_gather_varcount.rs
• examples/scatter_varcount.rs
• examples/gather_varcount.rs
• examples/wait_any.rs
• examples/contiguous.rs
• examples/immediate_scatter_varcount.rs
• examples/vector.rs
• examples/immediate_gather_varcount.rs
• examples/readme.rs
• examples/send_receive.rs
• examples/all_gather.rs
• examples/immediate_barrier.rs
• examples/immediate_all_gather.rs
• examples/gather.rs
• examples/group.rs
• examples/cartesian.rs
• examples/split.rs
• examples/immediate_gather.rs

fn rank(&self) -> Rank

The Rank that identifies the calling process within this communicator

Examples

See examples/simple.rs

Standard section(s)

6.4.1

Examples found in repository

examples/simple.rs (line 11)

fn main() {
    let universe = mpi::initialize().unwrap();
    let world = universe.world();
    println!(
        "Hello parallel world from process {} of {}!",
        world.rank(),
        world.size()
    );
}

examples/cartesian_map.rs (line 13)

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

    let comm = universe.world();

    let new_rank = comm.cartesian_map(&[2, comm.size() / 4], &[false, false]);

    println!("{} -> {:?}", comm.rank(), new_rank);
}

examples/all_gather_bool.rs (line 10)

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

    let rank = world.rank();
    let count = world.size() as usize;

    let mut a = vec![false; count];
    world.all_gather_into(&(rank % 2 == 0), &mut a[..]);

    let answer: Vec<_> = (0..count).map(|i| i % 2 == 0).collect();

    assert_eq!(answer, a);
}

examples/structured.rs (line 30)

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

    let root_process = world.process_at_rank(0);

    if world.rank() == 0 {
        root_process.broadcast_into(&mut MyInts([3, 2, 1]));
    } else {
        let mut ints: [i32; 3] = [0, 0, 0];
        root_process.broadcast_into(&mut ints[..]);

        assert_eq!([1, 2, 3], ints);
    }
}

examples/all_to_all.rs (line 9)

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];

    world.all_to_all_into(&u[..], &mut v[..]);

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

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

examples/scan.rs (line 15)

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

    let mut x = 0;
    world.scan_into(&rank, &mut x, &SystemOperation::sum());
    assert_eq!(x, (rank * (rank + 1)) / 2);

    let y = rank + 1;
    let mut z = 0;
    world.exclusive_scan_into(&y, &mut z, &SystemOperation::product());
    if rank > 0 {
        assert_eq!(z, fac(y - 1));
    }
}

Additional examples can be found in:

• examples/scatter.rs
• examples/immediate_all_to_all.rs
• examples/reduce.rs
• examples/datatype_dup.rs
• examples/immediate_reduce.rs
• examples/complex_datatype.rs
• examples/immediate_scan.rs
• examples/immediate_scatter.rs
• examples/barrier.rs
• examples/broadcast_complex.rs
• examples/all_gather_varcount.rs
• examples/ready_send.rs
• examples/broadcast.rs
• examples/immediate_all_gather_varcount.rs
• examples/scatter_varcount.rs
• examples/gather_varcount.rs
• examples/wait_any.rs
• examples/immediate_broadcast.rs
• examples/contiguous.rs
• examples/immediate_scatter_varcount.rs
• examples/vector.rs
• examples/immediate_gather_varcount.rs
• examples/readme.rs
• examples/send_receive.rs
• examples/all_gather.rs
• examples/immediate_barrier.rs
• examples/immediate_all_gather.rs
• examples/gather.rs
• examples/group.rs
• examples/cartesian.rs
• examples/split.rs
• examples/immediate_gather.rs

fn process_at_rank(&self, r: Rank) -> Process<'_, Self>

where Self: Sized,

Bundles a reference to this communicator with a specific Rank into a Process.

Examples

See examples/broadcast.rs examples/gather.rs examples/send_receive.rs

Examples found in repository

examples/structured.rs (line 28)

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

    let root_process = world.process_at_rank(0);

    if world.rank() == 0 {
        root_process.broadcast_into(&mut MyInts([3, 2, 1]));
    } else {
        let mut ints: [i32; 3] = [0, 0, 0];
        root_process.broadcast_into(&mut ints[..]);

        assert_eq!([1, 2, 3], ints);
    }
}

examples/scatter.rs (line 13)

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<_>>();
        root_process.scatter_into_root(&v[..], &mut x);
    } else {
        root_process.scatter_into(&mut x);
    }
    assert_eq!(x, rank);
}

examples/datatype_dup.rs (line 11)

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

    let root_process = world.process_at_rank(0);

    let int_type = i32::equivalent_datatype().dup();

    let mut ints = if world.rank() == 0 {
        [1i32, 2, 3, 4]
    } else {
        [0, 0, 0, 0]
    };

    let mut buffer =
        unsafe { DynBufferMut::from_raw(ints.as_mut_ptr(), ints.count(), int_type.as_ref()) };

    root_process.broadcast_into(&mut buffer);

    assert_eq!([1, 2, 3, 4], ints);
}

examples/complex_datatype.rs (line 55)

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

    let root_process = world.process_at_rank(0);

    let mut data = if world.rank() == 0 {
        ComplexDatatype {
            b: true,
            ints: [1, -2, 3, -4],
            tuple: TupleType([-0.1, 0.1], 7),
        }
    } else {
        ComplexDatatype::default()
    };

    root_process.broadcast_into(&mut data);

    assert_eq!(true, data.b);
    assert_eq!([1, -2, 3, -4], data.ints);
    assert_eq!([-0.1, 0.1], data.tuple.0);
    assert_eq!(7, data.tuple.1);
}

examples/immediate_scatter.rs (line 13)

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/barrier.rs (line 25)

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

    if world.rank() == receiver_rank {
        let n = (world.size() - 1) as usize;
        let mut buf = vec![0u64; 2 * n];
        for x in buf[0..n].iter_mut() {
            world.any_process().receive_into(x);
        }
        world.barrier();
        for x in buf[n..2 * n].iter_mut() {
            world.any_process().receive_into(x);
        }
        println!("{:?}", buf);
        assert!(buf[0..n].iter().all(|&x| x == 1));
        assert!(buf[n..2 * n].iter().all(|&x| x == 2));
    } else {
        world.process_at_rank(0).send(&1u64);
        world.barrier();
        world.process_at_rank(0).send(&2u64);
    }
}

Additional examples can be found in:

• examples/broadcast_complex.rs
• examples/ready_send.rs
• examples/broadcast.rs
• examples/scatter_varcount.rs
• examples/gather_varcount.rs
• examples/wait_any.rs
• examples/immediate_broadcast.rs
• examples/contiguous.rs
• examples/immediate_scatter_varcount.rs
• examples/vector.rs
• examples/immediate_gather_varcount.rs
• examples/readme.rs
• examples/send_receive.rs
• examples/immediate_reduce.rs
• examples/reduce.rs
• examples/immediate_barrier.rs
• examples/gather.rs
• examples/immediate_gather.rs

fn any_process(&self) -> AnyProcess<'_, Self>

where Self: Sized,

Returns an AnyProcess identifier that can be used, e.g. as a Source in point to point communication.

Examples found in repository

examples/barrier.rs (line 15)

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

    if world.rank() == receiver_rank {
        let n = (world.size() - 1) as usize;
        let mut buf = vec![0u64; 2 * n];
        for x in buf[0..n].iter_mut() {
            world.any_process().receive_into(x);
        }
        world.barrier();
        for x in buf[n..2 * n].iter_mut() {
            world.any_process().receive_into(x);
        }
        println!("{:?}", buf);
        assert!(buf[0..n].iter().all(|&x| x == 1));
        assert!(buf[n..2 * n].iter().all(|&x| x == 2));
    } else {
        world.process_at_rank(0).send(&1u64);
        world.barrier();
        world.process_at_rank(0).send(&2u64);
    }
}

examples/buffered.rs (line 27)

fn main() {
    let mut universe = mpi::initialize().unwrap();
    // Try to attach a buffer.
    universe.set_buffer_size(BUFFER_SIZE);
    // Check buffer size matches.
    assert_eq!(universe.buffer_size(), BUFFER_SIZE);
    // Try to detach the buffer.
    universe.detach_buffer();
    // Attach another buffer.
    universe.set_buffer_size(BUFFER_SIZE);

    let world = universe.world();

    let x = vec![std::f32::consts::PI; 1024];
    let mut y = vec![0.0; 1024];
    mpi::request::scope(|scope| {
        let _rreq = WaitGuard::from(
            world
                .any_process()
                .immediate_receive_into(scope, &mut y[..]),
        );
        world.this_process().buffered_send(&x[..]);
    });
    assert_eq!(x, y);
}

examples/wait_any.rs (line 36)

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| {
        if world.rank() == 0 {
            let mut requests = Vec::new();
            for i in 1..world.size() {
                requests.push(
                    world
                        .process_at_rank(i)
                        .immediate_synchronous_send(scope, &x),
                );
            }

            println!("World size {}", world.size());
            while let Some((index, _status)) = mpi::request::wait_any(&mut requests) {
                println!("Request with index {} completed", index);
            }
            println!("All requests completed");
        } else {
            let secs = time::Duration::from_secs(world.rank() as u64);

            thread::sleep(secs);

            let rreq = world.any_process().immediate_receive_into(scope, &mut y);
            rreq.wait();
            println!("Process {} received data", world.rank());
        }
    });
}

examples/readme.rs (line 24)

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

    let next_rank = if rank + 1 < size { rank + 1 } else { 0 };
    let previous_rank = if rank > 0 { rank - 1 } else { size - 1 };

    let msg = vec![rank, 2 * rank, 4 * rank];
    mpi::request::scope(|scope| {
        let _sreq = WaitGuard::from(
            world
                .process_at_rank(next_rank)
                .immediate_send(scope, &msg[..]),
        );

        let (msg, status) = world.any_process().receive_vec();

        println!(
            "Process {} got message {:?}.\nStatus is: {:?}",
            rank, msg, status
        );
        let x = status.source_rank();
        assert_eq!(x, previous_rank);
        assert_eq!(vec![x, 2 * x, 4 * x], msg);

        let root_rank = 0;
        let root_process = world.process_at_rank(root_rank);

        let mut a;
        if world.rank() == root_rank {
            a = vec![2, 4, 8, 16];
            println!("Root broadcasting value: {:?}.", &a[..]);
        } else {
            a = vec![0; 4];
        }
        root_process.broadcast_into(&mut a[..]);
        println!("Rank {} received value: {:?}.", world.rank(), &a[..]);
        assert_eq!(&a[..], &[2, 4, 8, 16]);
    });
}

examples/send_receive.rs (line 32)

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

    let next_rank = if rank + 1 < size { rank + 1 } else { 0 };
    let next_process = world.process_at_rank(next_rank);
    let previous_rank = if rank > 0 { rank - 1 } else { size - 1 };
    let previous_process = world.process_at_rank(previous_rank);

    let (msg, status): (Rank, _) = p2p::send_receive(&rank, &previous_process, &next_process);
    println!(
        "Process {} got message {}.\nStatus is: {:?}",
        rank, msg, status
    );
    world.barrier();
    assert_eq!(msg, next_rank);

    if rank > 0 {
        let msg = vec![rank, rank + 1, rank - 1];
        world.process_at_rank(0).send(&msg[..]);
    } else {
        for _ in 1..size {
            let (msg, status) = world.any_process().receive_vec::<Rank>();
            println!(
                "Process {} got long message {:?}.\nStatus is: {:?}",
                rank, msg, status
            );

            let x = status.source_rank();
            let v = vec![x, x + 1, x - 1];
            assert_eq!(v, msg);
        }
    }
    world.barrier();

    let mut x = rank;
    p2p::send_receive_replace_into(&mut x, &next_process, &previous_process);
    assert_eq!(x, previous_rank);
}

examples/immediate_barrier.rs (line 24)

fn main() {
    use mpi::traits::*;
    let universe = mpi::initialize().unwrap();
    let world = universe.world();
    let size = world.size();
    let receiver_rank = 0;

    if world.rank() == receiver_rank {
        // receiver process
        let n = (size - 1) as usize;
        let mut buf = vec![0u64; 3 * n];
        // receive first 2 * n messages
        for x in buf[0..2 * n].iter_mut() {
            world.any_process().receive_into(x);
        }
        // signal the waiting senders that 2 * n messages have been received
        let breq = world.immediate_barrier();
        // receive remaining n messages
        for x in buf[2 * n..3 * n].iter_mut() {
            world.any_process().receive_into(x);
        }
        println!("{:?}", buf);
        // messages "1" and "2" may be interleaved, but all have to be contained within the first
        // 2 * n slots of the buffer
        assert_eq!(buf[0..2 * n].iter().filter(|&&x| x == 1).count(), n);
        assert_eq!(buf[0..2 * n].iter().filter(|&&x| x == 2).count(), n);
        // the last n slots in the buffer may only contain message "3"
        assert!(buf[2 * n..3 * n].iter().all(|&x| x == 3));
        // clean up the barrier request
        breq.wait();
    } else {
        // sender processes
        // send message "1"
        world.process_at_rank(0).send(&1u64);
        // join barrier, but do not block
        let breq = world.immediate_barrier();
        // send message "2"
        world.process_at_rank(0).send(&2u64);
        // wait for receiver process to receive the first 2 * n messages
        breq.wait();
        // send message "3"
        world.process_at_rank(0).send(&3u64);
    }
}

Additional examples can be found in:

• examples/immediate.rs

fn this_process(&self) -> Process<'_, Self>

where Self: Sized,

A Process for the calling process

Examples found in repository

examples/buffered.rs (line 30)

fn main() {
    let mut universe = mpi::initialize().unwrap();
    // Try to attach a buffer.
    universe.set_buffer_size(BUFFER_SIZE);
    // Check buffer size matches.
    assert_eq!(universe.buffer_size(), BUFFER_SIZE);
    // Try to detach the buffer.
    universe.detach_buffer();
    // Attach another buffer.
    universe.set_buffer_size(BUFFER_SIZE);

    let world = universe.world();

    let x = vec![std::f32::consts::PI; 1024];
    let mut y = vec![0.0; 1024];
    mpi::request::scope(|scope| {
        let _rreq = WaitGuard::from(
            world
                .any_process()
                .immediate_receive_into(scope, &mut y[..]),
        );
        world.this_process().buffered_send(&x[..]);
    });
    assert_eq!(x, y);
}

examples/immediate.rs (line 16)

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

fn compare<C>(&self, other: &C) -> CommunicatorRelation

where C: Communicator + ?Sized,

Compare two communicators.

See enum CommunicatorRelation.

Standard section(s)

6.4.1

Examples found in repository

examples/duplicate.rs (line 15)

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

    world.barrier();
    moon.barrier();

    assert_eq!(CommunicatorRelation::Congruent, world.compare(&moon));
}

fn duplicate(&self) -> UserCommunicator

Duplicate a communicator.

Examples

See examples/duplicate.rs

Standard section(s)

6.4.2

Examples found in repository

examples/duplicate.rs (line 10)

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

    world.barrier();
    moon.barrier();

    assert_eq!(CommunicatorRelation::Congruent, world.compare(&moon));
}

fn split_by_color(&self, color: Color) -> Option<UserCommunicator>

Split a communicator by color.

Creates as many new communicators as distinct values of color are given. All processes with the same value of color join the same communicator. A process that passes the special undefined color will not join a new communicator and None is returned.

Examples

See examples/split.rs

Standard section(s)

6.4.2

Examples found in repository

examples/split.rs (line 65)

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

    let odd = (0..world.size()).filter(|x| x % 2 != 0).collect::<Vec<_>>();
    let odd_group = world.group().include(&odd[..]);
    let even_group = world.group().difference(&odd_group);
    assert!(
        (world.rank() % 2 == 0 && even_group.rank().is_some() && odd_group.rank().is_none())
            || (even_group.rank().is_none() && odd_group.rank().is_some())
    );
    let my_group = if odd_group.rank().is_some() {
        &odd_group
    } else {
        &even_group
    };
    let empty_group = SystemGroup::empty();

    let oddness_comm = world.split_by_subgroup_collective(my_group);
    assert!(oddness_comm.is_some());
    let oddness_comm = oddness_comm.unwrap();
    assert_eq!(
        GroupRelation::Identical,
        oddness_comm.group().compare(my_group)
    );

    let odd_comm = if odd_group.rank().is_some() {
        world.split_by_subgroup_collective(&odd_group)
    } else {
        world.split_by_subgroup_collective(&empty_group)
    };
    if odd_group.rank().is_some() {
        assert!(odd_comm.is_some());
        let odd_comm = odd_comm.unwrap();
        assert_eq!(
            GroupRelation::Identical,
            odd_comm.group().compare(&odd_group)
        );
    } else {
        assert!(odd_comm.is_none());
    }

    #[cfg(not(msmpi))]
    {
        if even_group.rank().is_some() {
            let even_comm = world.split_by_subgroup(&even_group);
            assert!(even_comm.is_some());
            let even_comm = even_comm.unwrap();
            assert_eq!(
                GroupRelation::Identical,
                even_comm.group().compare(&even_group)
            );

            let no_comm = world.split_by_subgroup(&odd_group);
            assert!(no_comm.is_none());
        }
    }

    let oddness_comm = world.split_by_color(Color::with_value(world.rank() % 2));
    assert!(oddness_comm.is_some());
    let oddness_comm = oddness_comm.unwrap();
    assert_eq!(
        GroupRelation::Identical,
        oddness_comm.group().compare(my_group)
    );

    let odd_comm = world.split_by_color(if world.rank() % 2 != 0 {
        Color::with_value(0)
    } else {
        Color::undefined()
    });
    if world.rank() % 2 != 0 {
        assert!(odd_comm.is_some());
        let odd_comm = odd_comm.unwrap();
        assert_eq!(
            GroupRelation::Identical,
            odd_comm.group().compare(&odd_group)
        );
    } else {
        assert!(odd_comm.is_none());
    }
}

fn split_by_color_with_key( &self, color: Color, key: Key, ) -> Option<UserCommunicator>

Split a communicator by color.

Like split() but orders processes according to the value of key in the new communicators.

Standard section(s)

6.4.2

fn split_shared(&self, key: c_int) -> UserCommunicator

Split the communicator into subcommunicators, each of which can create a shared memory region.

Within each subgroup, the processes are ranked in the order defined by the value of the argument key, with ties broken according to their rank in the old group.

Standard section(s)

6.4.2 (See: MPI_Comm_split_type)

fn split_by_subgroup_collective<G>(&self, group: &G) -> Option<UserCommunicator>

where G: Group + ?Sized,

Split a communicator collectively by subgroup.

Proceses pass in a group that is a subgroup of the group associated with the old communicator. Different processes may pass in different groups, but if two groups are different, they have to be disjunct. One new communicator is created for each distinct group. The new communicator is returned if a process is a member of the group he passed in, otherwise None.

This call is a collective operation on the old communicator so all processes have to partake.

Examples

See examples/split.rs

Standard section(s)

6.4.2

Examples found in repository

examples/split.rs (line 25)

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

    let odd = (0..world.size()).filter(|x| x % 2 != 0).collect::<Vec<_>>();
    let odd_group = world.group().include(&odd[..]);
    let even_group = world.group().difference(&odd_group);
    assert!(
        (world.rank() % 2 == 0 && even_group.rank().is_some() && odd_group.rank().is_none())
            || (even_group.rank().is_none() && odd_group.rank().is_some())
    );
    let my_group = if odd_group.rank().is_some() {
        &odd_group
    } else {
        &even_group
    };
    let empty_group = SystemGroup::empty();

    let oddness_comm = world.split_by_subgroup_collective(my_group);
    assert!(oddness_comm.is_some());
    let oddness_comm = oddness_comm.unwrap();
    assert_eq!(
        GroupRelation::Identical,
        oddness_comm.group().compare(my_group)
    );

    let odd_comm = if odd_group.rank().is_some() {
        world.split_by_subgroup_collective(&odd_group)
    } else {
        world.split_by_subgroup_collective(&empty_group)
    };
    if odd_group.rank().is_some() {
        assert!(odd_comm.is_some());
        let odd_comm = odd_comm.unwrap();
        assert_eq!(
            GroupRelation::Identical,
            odd_comm.group().compare(&odd_group)
        );
    } else {
        assert!(odd_comm.is_none());
    }

    #[cfg(not(msmpi))]
    {
        if even_group.rank().is_some() {
            let even_comm = world.split_by_subgroup(&even_group);
            assert!(even_comm.is_some());
            let even_comm = even_comm.unwrap();
            assert_eq!(
                GroupRelation::Identical,
                even_comm.group().compare(&even_group)
            );

            let no_comm = world.split_by_subgroup(&odd_group);
            assert!(no_comm.is_none());
        }
    }

    let oddness_comm = world.split_by_color(Color::with_value(world.rank() % 2));
    assert!(oddness_comm.is_some());
    let oddness_comm = oddness_comm.unwrap();
    assert_eq!(
        GroupRelation::Identical,
        oddness_comm.group().compare(my_group)
    );

    let odd_comm = world.split_by_color(if world.rank() % 2 != 0 {
        Color::with_value(0)
    } else {
        Color::undefined()
    });
    if world.rank() % 2 != 0 {
        assert!(odd_comm.is_some());
        let odd_comm = odd_comm.unwrap();
        assert_eq!(
            GroupRelation::Identical,
            odd_comm.group().compare(&odd_group)
        );
    } else {
        assert!(odd_comm.is_none());
    }
}

fn split_by_subgroup<G>(&self, group: &G) -> Option<UserCommunicator>

where G: Group + ?Sized,

Split a communicator by subgroup.

Like split_by_subgroup_collective() but not a collective operation.

Examples

See examples/split.rs

Standard section(s)

6.4.2

Examples found in repository

examples/split.rs (line 52)

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

    let odd = (0..world.size()).filter(|x| x % 2 != 0).collect::<Vec<_>>();
    let odd_group = world.group().include(&odd[..]);
    let even_group = world.group().difference(&odd_group);
    assert!(
        (world.rank() % 2 == 0 && even_group.rank().is_some() && odd_group.rank().is_none())
            || (even_group.rank().is_none() && odd_group.rank().is_some())
    );
    let my_group = if odd_group.rank().is_some() {
        &odd_group
    } else {
        &even_group
    };
    let empty_group = SystemGroup::empty();

    let oddness_comm = world.split_by_subgroup_collective(my_group);
    assert!(oddness_comm.is_some());
    let oddness_comm = oddness_comm.unwrap();
    assert_eq!(
        GroupRelation::Identical,
        oddness_comm.group().compare(my_group)
    );

    let odd_comm = if odd_group.rank().is_some() {
        world.split_by_subgroup_collective(&odd_group)
    } else {
        world.split_by_subgroup_collective(&empty_group)
    };
    if odd_group.rank().is_some() {
        assert!(odd_comm.is_some());
        let odd_comm = odd_comm.unwrap();
        assert_eq!(
            GroupRelation::Identical,
            odd_comm.group().compare(&odd_group)
        );
    } else {
        assert!(odd_comm.is_none());
    }

    #[cfg(not(msmpi))]
    {
        if even_group.rank().is_some() {
            let even_comm = world.split_by_subgroup(&even_group);
            assert!(even_comm.is_some());
            let even_comm = even_comm.unwrap();
            assert_eq!(
                GroupRelation::Identical,
                even_comm.group().compare(&even_group)
            );

            let no_comm = world.split_by_subgroup(&odd_group);
            assert!(no_comm.is_none());
        }
    }

    let oddness_comm = world.split_by_color(Color::with_value(world.rank() % 2));
    assert!(oddness_comm.is_some());
    let oddness_comm = oddness_comm.unwrap();
    assert_eq!(
        GroupRelation::Identical,
        oddness_comm.group().compare(my_group)
    );

    let odd_comm = world.split_by_color(if world.rank() % 2 != 0 {
        Color::with_value(0)
    } else {
        Color::undefined()
    });
    if world.rank() % 2 != 0 {
        assert!(odd_comm.is_some());
        let odd_comm = odd_comm.unwrap();
        assert_eq!(
            GroupRelation::Identical,
            odd_comm.group().compare(&odd_group)
        );
    } else {
        assert!(odd_comm.is_none());
    }
}

fn split_by_subgroup_with_tag<G>( &self, group: &G, tag: Tag, ) -> Option<UserCommunicator>

where G: Group + ?Sized,

Split a communicator by subgroup

Like split_by_subgroup() but can avoid collision of concurrent calls (i.e. multithreaded) by passing in distinct tags.

Standard section(s)

6.4.2

fn group(&self) -> UserGroup

The group associated with this communicator

Standard section(s)

6.3.2

Examples found in repository

examples/group.rs (line 12)

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

    let g = world.group();
    // Group accessors and Communicator accessors agree
    assert_eq!(world.size(), g.size());
    assert_eq!(world.rank(), g.rank().unwrap());

    // g == g
    assert_eq!(GroupRelation::Identical, g.compare(&g));

    let h = world.group();
    // h == g
    assert_eq!(GroupRelation::Identical, g.compare(&h));

    let i = g.union(&h);
    // g union h == g union g == g
    assert_eq!(GroupRelation::Identical, g.compare(&i));

    let empty = g.difference(&h);
    // g difference h == g difference g = empty Group
    assert_eq!(
        GroupRelation::Identical,
        SystemGroup::empty().compare(&empty)
    );
    assert_eq!(0, empty.size());

    // g intersection empty == empty Group
    assert_eq!(0, g.intersection(&empty).size());

    let first_half: Vec<Rank> = (0..g.size() / 2).collect();

    // f and s are first and second half of g
    let f = g.include(&first_half[..]);
    let s = g.exclude(&first_half[..]);
    // f != s
    assert_eq!(GroupRelation::Unequal, f.compare(&s));

    // g intersection f == f
    let f_ = g.intersection(&f);
    assert_eq!(GroupRelation::Identical, f.compare(&f_));
    // g intersection s == s
    let s_ = g.intersection(&s);
    assert_eq!(GroupRelation::Identical, s.compare(&s_));

    // g difference s == f
    let f__ = g.difference(&s);
    assert_eq!(GroupRelation::Identical, f.compare(&f__));
    // g difference f == s
    let s__ = g.difference(&f);
    assert_eq!(GroupRelation::Identical, s.compare(&s__));

    // f union s == g
    let fs = f.union(&s);
    assert_eq!(GroupRelation::Identical, g.compare(&fs));

    // f intersection s == empty Group
    let fs = f.intersection(&s);
    assert_eq!(GroupRelation::Identical, empty.compare(&fs));

    // rank is either in f or in s
    assert!(
        (f.rank().is_some() && s.rank().is_none()) ^ (f.rank().is_none() && s.rank().is_some())
    );

    // inverting rank mappings
    let rev: Vec<Rank> = (0..g.size()).rev().collect();
    let r = g.include(&rev[..]);
    assert_eq!(
        Some(rev[g.rank().unwrap() as usize]),
        r.translate_rank(g.rank().unwrap(), &g)
    );
}

examples/split.rs (line 12)

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

    let odd = (0..world.size()).filter(|x| x % 2 != 0).collect::<Vec<_>>();
    let odd_group = world.group().include(&odd[..]);
    let even_group = world.group().difference(&odd_group);
    assert!(
        (world.rank() % 2 == 0 && even_group.rank().is_some() && odd_group.rank().is_none())
            || (even_group.rank().is_none() && odd_group.rank().is_some())
    );
    let my_group = if odd_group.rank().is_some() {
        &odd_group
    } else {
        &even_group
    };
    let empty_group = SystemGroup::empty();

    let oddness_comm = world.split_by_subgroup_collective(my_group);
    assert!(oddness_comm.is_some());
    let oddness_comm = oddness_comm.unwrap();
    assert_eq!(
        GroupRelation::Identical,
        oddness_comm.group().compare(my_group)
    );

    let odd_comm = if odd_group.rank().is_some() {
        world.split_by_subgroup_collective(&odd_group)
    } else {
        world.split_by_subgroup_collective(&empty_group)
    };
    if odd_group.rank().is_some() {
        assert!(odd_comm.is_some());
        let odd_comm = odd_comm.unwrap();
        assert_eq!(
            GroupRelation::Identical,
            odd_comm.group().compare(&odd_group)
        );
    } else {
        assert!(odd_comm.is_none());
    }

    #[cfg(not(msmpi))]
    {
        if even_group.rank().is_some() {
            let even_comm = world.split_by_subgroup(&even_group);
            assert!(even_comm.is_some());
            let even_comm = even_comm.unwrap();
            assert_eq!(
                GroupRelation::Identical,
                even_comm.group().compare(&even_group)
            );

            let no_comm = world.split_by_subgroup(&odd_group);
            assert!(no_comm.is_none());
        }
    }

    let oddness_comm = world.split_by_color(Color::with_value(world.rank() % 2));
    assert!(oddness_comm.is_some());
    let oddness_comm = oddness_comm.unwrap();
    assert_eq!(
        GroupRelation::Identical,
        oddness_comm.group().compare(my_group)
    );

    let odd_comm = world.split_by_color(if world.rank() % 2 != 0 {
        Color::with_value(0)
    } else {
        Color::undefined()
    });
    if world.rank() % 2 != 0 {
        assert!(odd_comm.is_some());
        let odd_comm = odd_comm.unwrap();
        assert_eq!(
            GroupRelation::Identical,
            odd_comm.group().compare(&odd_group)
        );
    } else {
        assert!(odd_comm.is_none());
    }
}

fn abort(&self, errorcode: c_int) -> !

Abort program execution

Standard section(s)

8.7

fn set_name(&self, name: &str)

Set the communicator name

Standard section(s)

6.8, see the MPI_Comm_set_name function

Examples found in repository

examples/comm_name.rs (line 12)

fn main() {
    let universe = mpi::initialize().unwrap();
    let world = universe.world();
    assert_eq!("MPI_COMM_WORLD", world.get_name());
    world.set_name(CNAME);
    assert_eq!(CNAME, world.get_name());
}

fn get_name(&self) -> String

Get the communicator name

Standard section(s)

6.8, see the MPI_Comm_get_name function

Examples found in repository

examples/comm_name.rs (line 11)

fn main() {
    let universe = mpi::initialize().unwrap();
    let world = universe.world();
    assert_eq!("MPI_COMM_WORLD", world.get_name());
    world.set_name(CNAME);
    assert_eq!(CNAME, world.get_name());
}

fn create_cartesian_communicator( &self, dims: &[Count], periods: &[bool], reorder: bool, ) -> Option<CartesianCommunicator>

Creates a communicator with ranks laid out in a multi-dimensional space, allowing for easy neighbor-to-neighbor communication, while providing MPI with information to allow it to better optimize the physical locality of ranks that are logically close.

• dims - array of spatial extents for the cartesian space
• periods - Must match length of dims. For i in 0 to dims.len(), periods[i] indicates if axis i is periodic. i.e. if true, the element at dims[i] - 1 in axis i is a neighbor of element 0 in axis i
• reorder - If true, MPI may re-order ranks in the new communicator.

Standard section(s)

7.5.1 [MPI_Cart_create]

Examples found in repository

examples/cartesian.rs (line 20)

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

    let comm = universe.world();

    if comm.size() < 4 {
        return;
    }

    let cart_comm = {
        let dims = [2, 2];
        let periodic = [false, true];
        let reorder = true;
        if let Some(cart_comm) = comm.create_cartesian_communicator(&dims, &periodic, reorder) {
            cart_comm
        } else {
            assert!(comm.rank() >= 4);
            return;
        }
    };

    assert_eq!(2, cart_comm.num_dimensions());

    let mpi::topology::CartesianLayout {
        dims,
        periods,
        coords,
    } = cart_comm.get_layout();

    assert_eq!([2 as mpi::Count, 2], &dims[..]);
    assert_eq!([false, true], &periods[..]);

    let xrank = coords[0];
    let yrank = coords[1];

    assert!(0 <= xrank && xrank < 2);
    assert!(0 <= yrank && yrank < 2);

    let xcomm = cart_comm.subgroup(&[true, false]);
    let ycomm = cart_comm.subgroup(&[false, true]);

    assert_eq!(2, xcomm.size());
    assert_eq!(xrank, xcomm.rank());

    assert_eq!(2, ycomm.size());
    assert_eq!(yrank, ycomm.rank());

    // the first dimension is non-periodic
    let (x_src, x_dest) = cart_comm.shift(0, 1);
    if xrank == 0 {
        assert!(x_src.is_none());
        assert!(x_dest.is_some());

        let coords = cart_comm.rank_to_coordinates(x_dest.unwrap());
        assert_eq!(1, coords[0]);
    } else {
        assert_eq!(1, xrank);

        assert!(x_src.is_some());
        assert!(x_dest.is_none());

        let coords = cart_comm.rank_to_coordinates(x_src.unwrap());
        assert_eq!(0, coords[0]);
    }

    // the second dimension is periodic
    {
        let (y_src, y_dest) = cart_comm.shift(1, 1);
        assert!(y_src.is_some());
        assert!(y_dest.is_some());

        let y_src_coords = cart_comm.rank_to_coordinates(y_src.unwrap());
        assert_eq!((yrank - 1) & 0b1, y_src_coords[1]);

        let y_dest_coords = cart_comm.rank_to_coordinates(y_dest.unwrap());
        assert_eq!((yrank + 1) & 0b1, y_dest_coords[1]);
    }

    // second dimension shift by 2 should be identity
    {
        let (y_src, y_dest) = cart_comm.shift(1, 2);
        assert_eq!(comm.rank(), y_src.unwrap());
        assert_eq!(comm.rank(), y_dest.unwrap());
    }
}

fn cartesian_map(&self, dims: &[Count], periods: &[bool]) -> Option<Rank>

Gets the target rank of this rank as-if create_cartesian_communicator had been called with dims, periods, and reorder = true.

Returns None if the local process would not particate in the new CartesianCommunciator.

• dims - array of spatial extents for the cartesian space
• periods - Must match length of dims. For i in 0 to dims.len(), periods[i] indicates if axis i is periodic. i.e. if true, the element at dims[i] - 1 in axis i is a neighbor of element 0 in axis i

Standard section

7.5.8 [MPI_Cart_map]

Examples found in repository

examples/cartesian_map.rs (line 11)

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

    let comm = universe.world();

    let new_rank = comm.cartesian_map(&[2, comm.size() / 4], &[false, false]);

    println!("{} -> {:?}", comm.rank(), new_rank);
}

fn pack_size<Dt>(&self, incount: Count, datatype: &Dt) -> Count

where Dt: Datatype,

Gets the implementation-defined buffer size required to pack ‘incount’ elements of type ‘datatype’.

Standard section(s)

4.2, see [MPI_Pack_size]

fn pack<Buf>(&self, inbuf: &Buf) -> Vec<u8>

where Buf: ?Sized + Buffer,

Packs inbuf into a byte array with an implementation-defined format. Often paired with unpack to convert back into a specific datatype.

Standard Sections

4.2, see [MPI_Pack]

Examples found in repository

examples/pack.rs (line 11)

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

    let ints = [3i32, 2, 1];
    let packed = world.pack(&ints[..]);

    let mut new_ints = [0, 0, 0];
    unsafe {
        world.unpack_into(&packed, &mut new_ints[..], 0);
    }

    assert_eq!([3, 2, 1], new_ints);
}

fn pack_into<Buf>( &self, inbuf: &Buf, outbuf: &mut [u8], position: Count, ) -> Count

where Buf: ?Sized + Buffer,

Packs inbuf into a byte array with an implementation-defined format. Often paired with unpack to convert back into a specific datatype.

Standard Sections

4.2, see [MPI_Pack]

unsafe fn unpack_into<Buf>( &self, inbuf: &[u8], outbuf: &mut Buf, position: Count, ) -> Count

where Buf: ?Sized + BufferMut,

Unpacks an implementation-specific byte array from pack or pack_into into a buffer of a specific datatype.

Standard Sections

4.2, see [MPI_Unpack]

Safety

Unpacking must be succesfull

Examples found in repository

examples/pack.rs (line 15)

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

    let ints = [3i32, 2, 1];
    let packed = world.pack(&ints[..]);

    let mut new_ints = [0, 0, 0];
    unsafe {
        world.unpack_into(&packed, &mut new_ints[..], 0);
    }

    assert_eq!([3, 2, 1], new_ints);
}

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

impl Communicator for CartesianCommunicator

impl Communicator for SystemCommunicator

impl Communicator for UserCommunicator