Struct sharedlib::LibTracked

pub struct LibTracked<TLib> { /* fields omitted */ }

A shared library which which allows a user-provided ref-counting implementation to track its Symbols. The inner library will not be droped until all of teh ref-counts are dropped.

Methods

impl<TLib> LibTracked<TLib> where
    TLib: AsRef<LibUnsafe> + Clone + From<LibUnsafe>, 

unsafe fn new<TPath>(path_to_lib: TPath) -> Result<Self> where
    TPath: AsRef<Path>, 

Opens a shared library at the specified path. The path is used in conjunction with platform specific shared library search paths to determine which shared library will be opened. Search paths vary across environments and are not discussed in this documentation. The behavior of this function when it is called on the same path multiple times is platform specific. If you wish to obtain multiple copies of a library within the same code base in a platform generic way, you should load the symbol once in a LibTracked like LibArc, or LibRc, and pass around copies of the LibTracked.

Errors

A LibraryOpen error will be returned as a SharedlibError variant if there is a problem opening the shared library. For instance, this may happen if the shared library is not at the path specified.

Safety

Opening a shared library may execute code within the shared library. Since it is impossible to guarantee that the code witin the shared library is safe, the call to new is unsafe.

Examples

type LibRc = LibTracked<Rc<LibUnsafe>>;
let lib = try!(unsafe { LibRc::new("examplelib.dll") });

unsafe fn find_data<T, TStr>(
    &self,
    symbol: TStr
) -> Result<DataTracked<T, TLib>> where
    TStr: AsRef<str>, 

Finds and returns a data symbol within the shared library. By passing in a null terminated string, an extra allocation may be avoided.

Errors

A LibraryFindSymbol error will be returned as a SharedlibError variant if there is a problem finding the symbol. For instance, this may happen if the shared library does not contain the requested symbol.

Safety

This function is not type safe so there is no guarntee that T is really the type of the symbol. Using a symbol as a T when the symbol is not really of type T causes undefined behavior.

Examples

Finding data convieniently:

type DataRc<T> = DataTracked<T, Rc<LibUnsafe>>;
let some_usize: DataRc<usize> = try!(unsafe { lib.find_data("some_usize") });

Finding data with maximum performance:

type DataRc<T> = DataTracked<T, Rc<LibUnsafe>>;
let some_usize: DataRc<usize> = try!(unsafe { lib.find_data("some_usize\0") });

unsafe fn find_func<T, TStr>(
    &self,
    symbol: TStr
) -> Result<FuncTracked<T, TLib>> where
    T: Copy,
    TStr: AsRef<str>, 

Finds and returns a function symbol within the shared library. By passing in a null terminated string, an extra allocation may be avoided.

Errors

A LibraryFindSymbol error will be returned as a SharedlibError variant if there is a problem finding the symbol. For instance, this may happen if the shared library does not contain the requested symbol.

Safety

This function is not type safe so there is no guarntee that T is really the type of the symbol. Using a symbol as a T when the symbol is not really of type T causes undefined behavior.

Examples

Finding a function convieniently:

type FuncRc<T> = FuncTracked<T, Rc<LibUnsafe>>;
let some_func: FuncRc<fn()> = try!(unsafe { lib.find_func("some_func") });

Finding a function with maximum performance:

type FuncRc<T> = FuncTracked<T, Rc<LibUnsafe>>;
let some_func: FuncRc<fn()> = try!(unsafe { lib.find_func("some_func\0") });

Trait Implementations

impl<TLib: Clone> Clone for LibTracked<TLib>

fn clone(&self) -> LibTracked<TLib>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<TLib: Debug> Debug for LibTracked<TLib>

fn fmt(&self, __arg_0: &mut Formatter) -> Result

Formats the value using the given formatter.