Struct Mcl

pub struct Mcl { /* private fields */ }

Represents an initialize MCL environment. When this struct goes out of scope the MCL environment is finalized. Thus, there is no need to explicitly call the equivalent of (c-api) mcl_finit()

Implementations

impl Mcl

pub fn create_prog(&self, prog_path: &str, prog_type: PrgType) -> Prog

Creates a new mcl prog from the given source file pointed to by prog_path and the specified Program Type crate::prog::PrgType.

Returns a new Prog that can be loaded into the current mcl environment (that is load() will need to be called on it at a later time).

Examples

 use mcl_rs::{MclEnvBuilder,PrgType};

 let mcl = MclEnvBuilder::new().num_workers(10).initialize();
 mcl.create_prog("my_path",PrgType::Src);

pub fn load_prog(&self, prog_path: &str, prog_type: PrgType)

Creates and loads a new mcl prog from the given source file pointed to by prog_path and the specified Program Type crate::prog::PrgType.

This is a convenience function for when no additional arguments need to be supplied with program/kernel during compile time

Examples

 use mcl_rs::{MclEnvBuilder,PrgType};

 let mcl = MclEnvBuilder::new().num_workers(10).initialize();
 mcl.load_prog("my_path",PrgType::Src);

pub fn task<'a>(&self, kernel_name_cl: &str, nargs: usize) -> Task<'a>

Creates a new mcl task from the given kernel.

This kernel must exist in a previously loaded Prog.

Returns a new Task representing this kernel

Examples

     let mcl = mcl_rs::MclEnvBuilder::new().num_workers(10).initialize();
     mcl.load_prog("my_path", mcl_rs::PrgType::Src);

     let t = mcl.task("my_kernel", 2);

pub fn shared_task<'a>(&self, kernel_name_cl: &str, nargs: usize) -> Task<'a>

Available on crate features shared_mem or pocl_extensions only.

Creates a new mcl shared task from the given kernel.

This kernel must exist in a previously loaded Prog.

Other processes will be able to attach to this task by its shared task ID i.e. crate::task::Task::shared_id

Returns a new Task representing this kernel

Examples

     let mcl = mcl_rs::MclEnvBuilder::new().num_workers(10).initialize();
     mcl.load_prog("my_path", mcl_rs::PrgType::Src);

     let t = mcl.shared_task("my_kernel", 2);

pub fn attach_shared_task(&self, pid: i32, task_id: u32) -> SharedTask

Available on crate features shared_mem or pocl_extensions only.

Creates a new mcl shared task from the given process id and unique task id.

This task must have been created by process pid

Examples

     let mcl = mcl_rs::MclEnvBuilder::new().num_workers(10).initialize();
     mcl.load_prog("my_path", mcl_rs::PrgType::Src);
     let pid = 0; //user is required to set this approriately
     let task_id = 0; //user is required to set this approriately

     let t = mcl.attach_shared_task(pid,task_id);

pub fn transfer<'a>(&self, nargs: usize, ncopies: usize) -> Transfer<'a>

Creates a new mcl transfer task with that will transfer nargs and suggest to the scheduler that ncopies should be created

Examples

     let mcl = mcl_rs::MclEnvBuilder::new().initialize();
     mcl.load_prog("my_prog",mcl_rs::PrgType::Src);

     let tr = mcl.transfer(1, 1);

pub fn register_buffer<'a>(&self, arg: TaskArg<'a>) -> RegisteredBuffer<'a>

Register the provided arg as a buffer for future use with MCL resident memory

Panics

This call will panic if the provided TaskArg was not created from one of the slice variants: input_slice output_slice inout_slice

Further this call will also panic if the argument residient property was not set to true.

Examples

     let mcl = mcl_rs::MclEnvBuilder::new().initialize();
     mcl.load_prog("my_prog",mcl_rs::PrgType::Src);

     let mut a = vec![1;100];
     let buffer = mcl.register_buffer(mcl_rs::TaskArg::inout_slice(& mut a).resident(true));

pub fn create_shared_buffer(&self, arg: TaskArg<'_>) -> SharedMemBuffer

Available on crate features shared_mem or pocl_extensions only.

Creates a buffer that can be accessed via shared memory from multiple processes. If using only the “shared_mem” feature this buffer will be shared only in host memory. If the “pocl_extensions” feature is enabled, and the patched version of POCL 1.8 has been succesfully installed (please see https://github.com/pnnl/mcl/tree/dev#using-custom-pocl-extensions for more information)

Panics

This call will panic if the provided TaskArg was not created from one of the shared variants: input_shared output_shared inout_shared

Examples

     let mcl = mcl_rs::MclEnvBuilder::new().initialize();
     mcl.load_prog("my_prog",mcl_rs::PrgType::Src);
     let num_elems = 100;
     let buffer = mcl.create_shared_buffer(mcl_rs::TaskArg::inout_shared::<f32>("my_buffer",num_elems).resident(true));

pub fn attach_shared_buffer(&self, arg: TaskArg<'_>) -> SharedMemBuffer

Available on crate features shared_mem or pocl_extensions only.

Attaches to a shared buffer that was previously created by another process If using only the “shared_mem” feature this buffer will be shared only in host memory. If the “pocl_extensions” feature is enabled, and the patched version of POCL 1.8 has been succesfully installed (please see https://github.com/pnnl/mcl/tree/dev#using-custom-pocl-extensions for more information)

The provided TaskArg should have been constructed with identical arguments to the original buffer

Panics

This call will panic if the provided TaskArg was not created from one of the shared variants: input_shared output_shared inout_shared

Examples

     let mcl = mcl_rs::MclEnvBuilder::new().initialize();
     mcl.load_prog("my_prog",mcl_rs::PrgType::Src);
     let num_elems = 100;

     let buffer = mcl.attach_shared_buffer(mcl_rs::TaskArg::inout_shared::<f32>("my_buffer",num_elems).resident(true));

pub fn get_dev(&self, id: u32) -> DevInfo

Returns the info of the device specified by id

     let mcl = mcl_rs::MclEnvBuilder::new().num_workers(10).initialize();

     let t = mcl.task("my_kernel", 2);

pub fn get_ndev(&self) -> u32

Return the number of devices in the system

     let mcl = mcl_rs::MclEnvBuilder::new().initialize();
     let num_dev = mcl.get_ndev();