Struct tikv::coprocessor_v2::plugin_registry::PluginRegistry

pub struct PluginRegistry {
    inner: Arc<RwLock<PluginRegistryInner>>,
    fs_watcher: Option<RecommendedWatcher>,
}

Manages loading and unloading of coprocessor plugins.

Fields

inner: Arc<RwLock<PluginRegistryInner>>

fs_watcher: Option<RecommendedWatcher>

Active file system watcher for hot-reloading. If dropped, the corresponding hot-reloading thread will stop.

Implementations

impl PluginRegistry

pub fn new() -> Self

Creates a new PluginRegistry.

pub fn start_hot_reloading(
    &mut self,
    plugin_directory: impl Into<PathBuf>
) -> Result<()>

Hot-reloads plugins from a given directory.

All plugins that are already present in the directory will be loaded. A background thread is spawned to watch file system events. If the library file of a loaded plugin is deleted, the corresponding plugin is automatically unloaded; if a new library file is placed into the directory, it will be automatically loaded into TiKV’s coprocessor plugin system.

A file will only be loaded if it has the proper file ending of dynamic link libraries for the current platform (.so for Linux, .dylib for MacOS, .dll for Windows).

pub fn get_plugin(&self, plugin_name: &str) -> Option<Arc<LoadedPlugin>>

Finds a plugin by its name. The plugin must have been loaded before with [load_plugin()].

Plugins are indexed by the name that is returned by [CoprocessorPlugin::name()].

pub fn get_plugin_by_path<P: AsRef<OsStr>>(
    &self,
    plugin_path: P
) -> Option<Arc<LoadedPlugin>>

finds a plugin by its associated file path, similar to [get_plugin()].

The given path has to be exactly the same as the one the plugin with loaded with, e.g. "./coprocessors/plugin1.so" would be different from "coprocessors/plugin1.so" (note the leading ./). The same applies when the associated path was changed with [update_plugin_path()].

pub fn loaded_plugin_names(&self) -> Vec<String>

Returns the names of the currently loaded plugins. The order of plugin names is arbitrary.

pub fn load_plugin<P: AsRef<OsStr>>(
    &self,
    file_name: P
) -> Result<String, PluginLoadingError>

Loads a CoprocessorPlugin from a dylib.

After this function has successfully finished, the plugin is registered with the PluginRegistry and can later be obtained by calling [get_plugin()] with the proper name.

Returns the name of the loaded plugin.

pub fn load_plugins_from_dir(
    &self,
    dir_name: impl Into<PathBuf>
) -> Result<Vec<String>>

Attempts to load all plugins from a given directory.

Returns a list of the names of all successfully loaded plugins. If a file could not be successfully loaded as a plugin, it will be discarded.

The plugins have to follow the system’s naming convention in order to be loaded, e.g. .so for Linux, .dylib for MacOS and .dll for Windows.

pub fn unload_plugin(&self, plugin_name: &str)

Unloads a plugin with the given plugin_name.

pub fn update_plugin_path<P: AsRef<OsStr>>(
    &self,
    plugin_name: &str,
    new_path: P
)

Updates the associated file path for plugin.

This function should be used to maintain consistent state when the underlying file of a plugin was renamed or moved.

pub fn get_path_for_plugin(&self, plugin_name: &str) -> Option<OsString>

Returns the associated file path for the plugin for the given plugin_name.