Struct cust::module::Module

pub struct Module { /* private fields */ }

A compiled CUDA module, loaded into a context.

Implementations

impl Module

pub fn from_file<P: AsRef<Path>>(path: P) -> CudaResult<Module>

Load a module from the given path into the current context.

The given path should be either a cubin file, a ptx file, or a fatbin file such as those produced by nvcc.

Example

use cust::module::Module;
use std::ffi::CString;

let module = Module::from_file("./resources/add.ptx")?;

pub fn from_fatbin<T: AsRef<[u8]>>(
    bytes: T,
    options: &[ModuleJitOption]
) -> CudaResult<Module>

Creates a new module by loading a fatbin (fat binary) file.

Fatbinary files are files that contain multiple ptx or cubin files. The driver will choose already-built cubin if it is present, and otherwise JIT compile any PTX in the file to cubin.

Example

use cust::module::Module;
let fatbin_bytes = std::fs::read("./resources/add.fatbin")?;
// will return InvalidSource if the fatbin does not contain any compatible code, meaning, either
// cubin compiled for the same device architecture OR PTX that can be JITted into valid code.
let module = Module::from_fatbin(&fatbin_bytes, &[])?;

pub fn from_cubin<T: AsRef<[u8]>>(
    bytes: T,
    options: &[ModuleJitOption]
) -> CudaResult<Module>

Creates a new module by loading a cubin (CUDA Binary) file.

Cubins are architecture/compute-capability specific files generated as the final step of the CUDA compilation process. They cannot be interchanged across compute capabilities unlike PTX (to some degree). You can create one using the PTX compiler APIs, the cust Linker, or nvcc (nvcc a.ptx --cubin -arch=sm_XX).

Example

use cust::module::Module;
let cubin_bytes = std::fs::read("./resources/add.cubin")?;
// will return InvalidSource if the cubin arch doesn't match the context's device arch!
let module = Module::from_cubin(&cubin_bytes, &[])?;

pub fn from_ptx_cstr(
    cstr: &CStr,
    options: &[ModuleJitOption]
) -> CudaResult<Module>

Creates a new module from a CStr pointing to PTX code.

The driver will JIT the PTX into arch-specific cubin or pick already-cached cubin if available.

pub fn from_ptx<T: AsRef<str>>(
    string: T,
    options: &[ModuleJitOption]
) -> CudaResult<Module>

Creates a new module from a PTX string, allocating an intermediate buffer for the CString.

The driver will JIT the PTX into arch-specific cubin or pick already-cached cubin if available.

Panics

Panics if string contains a nul.

Example

use cust::module::Module;
let ptx = std::fs::read("./resources/add.ptx")?;
let module = Module::from_ptx(&ptx, &[])?;

pub fn from_str<T: AsRef<str>>(string: T) -> CudaResult<Module>

👎 Deprecated since 0.3.0:

from_str was too generic of a name, use from_ptx instead, passing an empty slice of options (usually)

Load a module from a normal (rust) string, implicitly making it into a cstring.

pub fn load_from_string(image: &CStr) -> CudaResult<Module>

👎 Deprecated since 0.3.0:

load_from_string was an inconsistent name with inconsistent params, use from_ptx/from_ptx_cstr, passing an empty slice of options (usually)

Load a module from a CStr.

This is useful in combination with include_str!, to include the device code into the compiled executable.

The given CStr must contain the bytes of a cubin file, a ptx file or a fatbin file such as those produced by nvcc.

Example

use cust::module::Module;
use std::ffi::CString;

let image = CString::new(include_str!("../resources/add.ptx"))?;
let module = Module::load_from_string(&image)?;

pub fn get_global<'a, T: DeviceCopy>(
    &'a self,
    name: &CStr
) -> CudaResult<Symbol<'a, T>>

Get a reference to a global symbol, which can then be copied to/from.

Panics:

This function panics if the size of the symbol is not the same as the mem::sizeof<T>().

Examples

use cust::module::Module;
use std::ffi::CString;

let ptx = CString::new(include_str!("../resources/add.ptx"))?;
let module = Module::load_from_string(&ptx)?;
let name = CString::new("my_constant")?;
let symbol = module.get_global::<u32>(&name)?;
let mut host_const = 0;
symbol.copy_to(&mut host_const)?;
assert_eq!(314, host_const);

pub fn get_function<T: AsRef<str>>(&self, name: T) -> CudaResult<Function<'_>>

Get a reference to a kernel function which can then be launched.

Examples

use cust::module::Module;
use std::ffi::CString;

let ptx = CString::new(include_str!("../resources/add.ptx"))?;
let module = Module::load_from_string(&ptx)?;
let function = module.get_function("sum")?;

pub fn drop(module: Module) -> DropResult<Module>

Destroy a Module, returning an error.

Destroying a module can return errors from previous asynchronous work. This function destroys the given module and returns the error and the un-destroyed module on failure.

Example

use cust::module::Module;
use std::ffi::CString;

let ptx = CString::new(include_str!("../resources/add.ptx"))?;
let module = Module::load_from_string(&ptx)?;
match Module::drop(module) {
    Ok(()) => println!("Successfully destroyed"),
    Err((e, module)) => {
        println!("Failed to destroy module: {:?}", e);
        // Do something with module
    },
}

Trait Implementations

impl Debug for Module

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

Formats the value using the given formatter.

impl Drop for Module

fn drop(&mut self)

Executes the destructor for this type.

impl Send for Module

impl Sync for Module