pub struct Module { /* private fields */ }
Expand description
A compiled CUDA module, loaded into a context.
Implementations
sourceimpl Module
impl Module
sourcepub fn from_file<P: AsRef<Path>>(path: P) -> CudaResult<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")?;
sourcepub fn from_fatbin<T: AsRef<[u8]>>(
bytes: T,
options: &[ModuleJitOption]
) -> CudaResult<Module>
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, &[])?;
sourcepub fn from_cubin<T: AsRef<[u8]>>(
bytes: T,
options: &[ModuleJitOption]
) -> CudaResult<Module>
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, &[])?;
sourcepub fn from_ptx_cstr(
cstr: &CStr,
options: &[ModuleJitOption]
) -> CudaResult<Module>
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.
sourcepub fn from_ptx<T: AsRef<str>>(
string: T,
options: &[ModuleJitOption]
) -> CudaResult<Module>
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, &[])?;
sourcepub 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)
pub fn from_str<T: AsRef<str>>(string: T) -> CudaResult<Module>
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.
sourcepub 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)
pub fn load_from_string(image: &CStr) -> CudaResult<Module>
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)?;
sourcepub fn get_global<'a, T: DeviceCopy>(
&'a self,
name: &CStr
) -> CudaResult<Symbol<'a, T>>
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);
sourcepub fn get_function<T: AsRef<str>>(&self, name: T) -> CudaResult<Function<'_>>
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")?;
sourcepub fn drop(module: Module) -> DropResult<Module>
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
Auto Trait Implementations
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcepub fn borrow_mut(&mut self) -> &mut T
pub fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more