Attribute Macro memflow_derive::connector

#[connector]

Creates a memflow connector plugin. This function takes care of supplying all necessary underlying structures for exposing a memflow connector plugin in the form of a dylib.

Remarks:

We should add conditional compilation for the crate-type here so our rust libraries who use a connector wont export those functions again by themselves (e.g. the ffi).

This would also lead to possible duplicated symbols if multiple connectors are imported.

See https://github.com/rust-lang/rust/issues/20267 for the tracking issue.

#[cfg(crate_type = “cdylib”)]

Macro Parameters:

name - The name of the plugin version - The version of the plugin description - Short description of the plugin help_fn - Name of the function that provides a help text to the user target_list_fn - Name of the function that provides a list of all targets to the user accept_input - Wether or not this Connector is able to accept an Os-Plugin as an input return_wrapped - Wether or not the return value is an already wrapped cglue object or if the macro needs to construct it no_default_cache - Disables the default caching behavior if no cache configuration is supplied by the user.

Caching:

By default the proc macro will call memflow::plugins::connector::create_instance internally which will handle the caching functionality. Either the user did not specify any caching, which results in the default caching configuration being used, or the user did choose a custom caching configuration which will override the default caching configuration.

In case no_default_cache is used the default behavior will be to use no caching. If the user supplies a cache configuration even if no_default_cache is set the memflow::plugins::connector::create_instance function will still instantiate the requested configuration.

In case return_wrapped is set to true the caching behavior has to be handled by the end user simply by calling memflow::plugins::connector::create_instance with the appropiate arguments.

Examples:

Simple usage:

#[connector(name = "dummy_conn", version = "1.0.0", description = "Dummy Plugin for Testing purposes")]
pub fn create_connector(_args: &ConnectorArgs) -> Result<DummyMemory> {
    Ok(DummyMemory::new(size::mb(16)))
}

Disable default caching:

#[connector(name = "dummy_conn", no_default_cache = true)]
pub fn create_connector(_args: &ConnectorArgs) -> Result<DummyMemory> {
    Ok(DummyMemory::new(size::mb(16)))
}

Custom help function:

#[connector(name = "dummy_conn", help_fn = "help")]
pub fn create_connector(_args: &ConnectorArgs) -> Result<DummyMemory> {
    Ok(DummyMemory::new(size::mb(16)))
}

pub fn help() -> String {
    "Dummy Plugin for Testing purposes".to_string()
}

Custom target list function:

#[connector(name = "dummy_conn", target_list_fn = "target_list")]
pub fn create_connector(_args: &ConnectorArgs) -> Result<DummyMemory> {
    Ok(DummyMemory::new(size::mb(16)))
}

pub fn target_list() -> Result<Vec<TargetInfo>> {
    Ok(Vec::new())
}

Wrapped return with manually created connector instance:

#[connector(name = "dummy_conn", return_wrapped = true)]
pub fn create_connector(
    args: &ConnectorArgs,
    lib: LibArc,
) -> Result<ConnectorInstanceArcBox<'static>> {
    let connector = DummyMemory::new(size::mb(16));
    Ok(memflow::plugins::connector::create_instance(connector, lib, args, false))
}

Connector with input parameter:

#[connector(name = "dummy_conn", accept_input = true)]
pub fn create_connector(
    _args: &ConnectorArgs,
    _os: Option<OsInstanceArcBox<'static>>,
) -> Result<DummyMemory> {
    Ok(DummyMemory::new(size::mb(16)))
}

Connector with input parameter and manually created connector instance:

#[connector(name = "dummy_conn", accept_input = true, return_wrapped = true)]
pub fn create_connector<'a>(
    args: &ConnectorArgs,
    _os: Option<OsInstanceArcBox<'static>>,
    lib: LibArc,
) -> Result<ConnectorInstanceArcBox<'static>> {
    let connector = DummyMemory::new(size::mb(16));
    Ok(memflow::plugins::connector::create_instance(connector, lib, args, false))
}