Mirror/zeek
1
0
Fork 0
mirror of https://github.com/zeek/zeek.git synced 2025-10-04 23:58:20 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Polishing, mostly documentation updates.

Browse source
This commit is contained in:
Robin Sommer 2014-06-17 11:50:23 -07:00
parent 551950c438
commit 60cf0ddf26
9 changed files with 294 additions and 179 deletions
Download patch file Download diff file Expand all files Collapse all files

130
src/plugin/Manager.h
View file

@ -12,14 +12,31 @@
namespace plugin {
// Macros that trigger a plugin hook. We put this into macros to short-cut
// the code for the most common case that no plugin defines the hook.
#define PLUGIN_HOOK_WITH_RESULT(hook, method_call, default_result) \
(plugin_mgr->HavePluginForHook(::plugin::hook) ? plugin_mgr->method_call : (default_result))
// Macros that trigger plugin hooks. We put this into macros to short-cut the
// code for the most common case that no plugin defines the hook.
/**
* Macro to trigger hooks without result.
*
* @param hook The \a plugin::HookType constant corresponding to the hook to trigger.
*
* @param method_call The \a Manager method corresponding to the hook.
*/
#define PLUGIN_HOOK_VOID(hook, method_call) \
if ( plugin_mgr->HavePluginForHook(plugin::hook) ) plugin_mgr->method_call;
/**
* Macro to trigger hooks that return a result.
*
* @param hook The \a plugin::HookType constant corresponding to the hook to trigger.
*
* @param method_call The \a Manager method corresponding to the hook.
*
* @param default_result: The result to use if there's no plugin implementing
* the hook.
*/
#define PLUGIN_HOOK_WITH_RESULT(hook, method_call, default_result) \
(plugin_mgr->HavePluginForHook(::plugin::hook) ? plugin_mgr->method_call : (default_result))
/**
* A singleton object managing all plugins.
@ -43,24 +60,24 @@ public:
virtual ~Manager();
/**
* Searches a set of directories for plugins. If a specificed
* directory does not contain a plugin itself, the method searches
* for plugins recursively. For plugins found, the method makes them
* available for later activation via ActivatePlugin().
* Searches a set of directories for plugins. If a specified directory
* does not contain a plugin itself, the method searches for plugins
* recursively. For plugins found, the method makes them available for
* later activation via ActivatePlugin().
*
* This must be called only before InitPluginsPreScript().
*
* @param dir The directory to search for plugins. Multiple
* directories are split by ':'.
* @param dir The directory to search for plugins. Multiple directories
* can be given by splitting them with ':'.
*/
void SearchDynamicPlugins(const std::string& dir);
/**
* Activates a plugin that SearchPlugins() has previously discovered.
* Activing a plugin involved loading its dynamic module, making its
* Activating a plugin involves loading its dynamic module, making its
* bifs available, and adding its script paths to BROPATH.
*
* @param name The name of the plugin, as determined previously by
* @param name The name of the plugin, as found previously by
* SearchPlugin().
*
* @return True if the plugin has been loaded successfully.
@ -70,15 +87,15 @@ public:
/**
* Activates plugins that SearchPlugins() has previously discovered. The
* effect is the same all calling \a ActivePlugin(name) for the plugins.
* effect is the same all calling \a ActivePlugin(name) for each plugin.
*
* @param all If true, activates all plugins that are found. If false,
* activate only those that should always be activated unconditionally
* via the BRO_PLUGIN_ACTIVATE enviroment variable. In other words, it's
* false if running bare mode.
* activates only those that should always be activated unconditionally,
* as specified via the BRO_PLUGIN_ACTIVATE enviroment variable. In other
* words, it's \c true in standard mode and \c false in bare mode.
*
* @return True if all plugins have been loaded successfully. If one
* fail to load, the method stops there without loading any furthers
* fails to load, the method stops there without loading any further ones
* and returns false.
*/
bool ActivateDynamicPlugins(bool all);
@ -91,30 +108,30 @@ public:
void InitPreScript();
/**
* Second-stage initialization of the manager. This is called in
* between pre- and post-script to make BiFs available.
* Second-stage initialization of the manager. This is called in between
* pre- and post-script to make BiFs available.
*/
void InitBifs();
/**
* Third-stage initialization of the manager. This is called late
* during Bro's initialization after any scripts are processed, and
* forwards to the corresponding Plugin methods.
* Third-stage initialization of the manager. This is called late during
* Bro's initialization after any scripts are processed, and forwards to
* the corresponding Plugin methods.
*/
void InitPostScript();
/**
* Finalizes all plugins at termination time. This forwards to the
* corresponding Plugin methods.
* corresponding Plugin \a Done() methods.
*/
void FinishPlugins();
/**
* Returns a list of all available and activated plugins. This includes
* all that are compiled in statically, as well as those loaded
* dynamically so far.
* Returns a list of all available activated plugins. This includes all
* that are compiled in statically, as well as those loaded dynamically
* so far.
*/
plugin_list Plugins() const;
plugin_list ActivePlugins() const;
/**
* Returns a list of all dynamic plugins that have been found, yet not
@ -141,7 +158,7 @@ public:
*/
bool HavePluginForHook(HookType hook) const
{
// Inline to make avoid the function call.
// Inline to avoid the function call.
return hooks[hook] != 0;
}
@ -174,8 +191,12 @@ public:
void DisableHook(HookType hook, Plugin* plugin);
/**
* Register interest in an event. The event will then be raised, and
* hence passed to the plugin, even if there no handler defined.
* Registers interest in an event by a plugin, even if there's no handler
* for it. Normally a plugin receives events through HookQueueEvent()
* only if Bro actually has code to execute for it. By calling this
* method, the plugin tells Bro to raise the event even if there's no
* correspondong handler; it will then go into HookQueueEvent() just as
* any other.
*
* @param handler The event being interested in.
*
@ -184,9 +205,9 @@ public:
void RequestEvent(EventHandlerPtr handler, Plugin* plugin);
/**
* Register interest in the destruction of a BroObj instance. When
* Bro's reference counting triggers the objects destructor to run,
* the \a HookBroObjDtor will be called.
* Register interest in the destruction of a BroObj instance. When Bro's
* reference counting triggers the objects destructor to run, the \a
* HookBroObjDtor will be called.
*
* @param handler The object being interested in.
*
@ -197,16 +218,16 @@ public:
// Hook entry functions.
/**
* Hook that gives plugins a chance to take over loading an input
* input file. This method must be called between InitPreScript() and
* Hook that gives plugins a chance to take over loading an input input
* file. This method must be called between InitPreScript() and
* InitPostScript() for each input file Bro is about to load, either
* given on the command line or via @load script directives. The hook
* can take over the file, in which case Bro must not further process
* it otherwise.
* given on the command line or via @load script directives. The hook can
* take over the file, in which case Bro must not further process it
* otherwise.
*
* @return 1 if a plugin took over the file and loaded it
* successfully; 0 if a plugin took over the file but had trouble
* loading it; and -1 if no plugin was interested in the file at all.
* @return 1 if a plugin took over the file and loaded it successfully; 0
* if a plugin took over the file but had trouble loading it; and -1 if
* no plugin was interested in the file at all.
*/
virtual int HookLoadFile(const string& file);
@ -215,12 +236,13 @@ public:
*
* @param func The function to be called.
*
* @param args The function call's arguments; they may be modified.
* @param args The function call's arguments; they may be modified by the
* method.
*
* @return If a plugin handled the call, a +1 Val with the result
* value to pass back to the interpreter (for void functions and
* events, it may be any Val and must be ignored). If no plugin
* handled the call, the method returns null.
* @return If a plugin handled the call, a Val with a +1 reference count
* containing the result value to pass back to the interpreter (for void
* functions and events, it may be any Val and must be ignored). If no
* plugin handled the call, the method returns null.
*/
Val* HookCallFunction(const Func* func, val_list* args) const;
@ -263,7 +285,12 @@ public:
static void RegisterPlugin(Plugin* plugin);
/**
* Internal method that registers a bif file's init function for a plugin.
* Internal method that registers a bif file's init function for a
* plugin.
*
* @param plugin The plugin to reguster the function for.
*
* @param c The init function to register.
*/
static void RegisterBifFile(const char* plugin, bif_init_func c);
@ -277,12 +304,12 @@ private:
typedef std::map<std::string, std::string> dynamic_plugin_map;
dynamic_plugin_map dynamic_plugins;
// We buffer scripts to load temporarliy to get them to load in the
// We temporarliy buffer scripts to load to get them to load in the
// right order.
typedef std::list<std::string> file_list;
file_list scripts_to_load;
bool init;
bool init; // Flag indicating whether InitPreScript() has run yet.
// A hook list keeps pairs of plugin and priority interested in a
// given hook.
@ -292,6 +319,7 @@ private:
// of that type enabled.
hook_list** hooks;
// Helpers providing access to current state during dlopen().
static Plugin* current_plugin;
static string current_dir;
static string current_sopath;
@ -299,7 +327,7 @@ private:
// Returns a modifiable list of all plugins, both static and dynamic.
// This is a static method so that plugins can register themselves
// even before the manager exists.
static plugin_list* PluginsInternal();
static plugin_list* ActivePluginsInternal();
typedef std::list<bif_init_func> bif_init_func_list;
typedef std::map<std::string, bif_init_func_list*> bif_init_func_map;
@ -315,7 +343,7 @@ std::list<T *> Manager::Components() const
{
std::list<T *> result;
for ( plugin_list::const_iterator p = PluginsInternal()->begin(); p != PluginsInternal()->end(); p++ )
for ( plugin_list::const_iterator p = ActivePluginsInternal()->begin(); p != ActivePluginsInternal()->end(); p++ )
{
component_list components = (*p)->Components();