NAME

       elektra-plugins-framework - Background about plugins framework

       Many  component systems pass information between the various components by calling methods
       of each other. This is not the way Elektra´s plugin system works. Instead, the core passes
       a  KeySet  object  in  one  direction  from  plugin  to  plugin.  So they form a so called
       pipes-and-filter. Each of the plugins can  modify  the  configuration  or  add  any  other
       information  using  metakeys.  While  this  approach  is  in  general  less flexible, this
       information flow still allows powerful chaining. Because plugins do not have to bother  to
       call  other  plugins,  the  plugin  development is also easier. The ordering of plugins in
       backends is controlled using contracts.

Contracts

       Every plugin should provide a full contract to give information  how  it  will  work  with
       other plugins. Most parts of the contract are obligatory. Plugins cannot be loaded without
       this information. For example, plugins must provide the clause infos/version. It is  vital
       so that the plugin loader knows which version of Elektra the plugin was built for.

Conditions

       It  is,  however,  up to the plugin not to have every clause of the contract. For example,
       the plugin might not tell what it provides or needs. It can  also  leave  any  description
       out.  In  this  situation  it is unclear what the plugin will do. Such a plugin can add or
       remove keys, and changes values and metadata regardless what other plugins expect. If only
       such  plugins  existed  there  would  be  chaos.  It  would be impossible to determine the
       behaviour of a backend which uses a multiple of such plugins.

       To avoid this situation, every  plugin  exports  a  contract  describing  how  the  plugin
       modifies the KeySet returned. Most often it is enough to state that it is a storage plugin
       or that it will filter keys.

       The  data  structures,  however,  are  already  responsible  for  most  of  the  pre-  and
       postconditions.  Every  condition  the data structure guarantees, takes away a concern for
       the plugins. All the parts that are already guaranteed by data structures do not  need  to
       be stated in the contract.

       Plugins should not be burdened to check too many postconditions. Instead, plugins focus on
       their task. The plugin does not need to check the sync flag of keys or  if  the  keys  are
       below  the  mount  point.  The  core  already guarantees correct behaviour as described in
       algorithm /doc/help/elektra-algorithm.md.

       To sum up, contracts give the information how a plugin interacts with others. It describes
       if,  and  how,  the  KeySet  returned  is  changed.  Using contracts, we get a predictable
       behaviour, but still support every kind of plugin.

Exporting Contracts

       As already stated, some parts of the contracts are obligatory. kdb  mount  needs  to  know
       which  symbols the plugin exports. Only the elektraPluginGet() symbol is mandatory - it is
       used to yield this information. Elektra´s core also uses the functions elektraPluginSet(),
       elektraPluginError(),  elektraPluginOpen()  and  elektraPluginClose()  if available. Other
       functions like serialise, unserialise or lookup which implement special  features  can  be
       supported, but are ignored by the core. For the user of the library these functions can be
       very useful. These functions shall either belong to  the  concern  of  the  plugin  or  be
       implemented within the plugin because of the dependences.

       As  described in infos/provides /doc/CONTRACT.ini, the plugin can also provide descriptive
       information, for example about the author and  the  licence.  Advanced  plugins  can  also
       export  plugin configuration for other plugins so that the overall backend works properly.
       Last, but not least, as enumerated in  infos/placement  /doc/CONTRACT.ini  dependency  and
       placement information makes the system reliable and robust. With that information, plugins
       can be placed into a backend in an automatic and secure way.

       system/elektra/modules provides for every module  the  information  described  above.  The
       entry  exists  once  a  plugin  of that module is loaded. For each module a special module
       backend   is   generated   and   mounted   at   system/elektra/modules/<pluginname>.   The
       elektraPluginGet() function generates this described contract on requests.

       For example, the ccode plugin, implements:

           int elektraCcodeGet(Plugin *handle, KeySet *returned, Key *parentKey)
           {
               if (!strcmp (keyName(parentKey), "system/elektra/modules/ccode"))
               {
                   KeySet *contract = ksNew (30,
                       keyNew ("system/elektra/modules/ccode",
                           KEY_END),
                       keyNew ("system/elektra/modules/ccode/exports",
                           KEY_END),
                       //...
                       KS_END);
                   ksAppend (returned, contract);
                   ksDel (contract);
                   return 1;
               }
               // implementation of elektraCcodeGet

       We  see  in  Listing above that the plugin generates and returns the contract if, and only
       if, the name of the parentKey is system/elektra/modules/ccode. The user and  the  contract
       checker can access the contract of ccode below the key system/elektra/modules/ccode in the
       same way other configuration is accessed. Note that we also have to return 1 at the end of
       the contract to not execute the regular functionality of the plugin.

Changing Plugins

       This  configuration  is  static  and  contains  the  contract  information. In theory, the
       contract can be changed without any problems in ways that it provides more  and  obligates
       less. But the problem is that it will not be checked if this is the case because a recheck
       of the contracts of a backend is very expensive. The contract  checker  doing  this,  only
       runs  once during mount time. Changing contracts in an incompatible way forces the user to
       remove all mount points where the plugin is and mount it  again.  Such  actions  are  only
       sustainable in a development phase and not in a productive environment.

       But  the  plugin´s  implementation is allowed to change without being remounted if it is a
       subtype of the earlier version. Only in this situation it can be a drop-in placement. With
       a good testing framework the behaviour can be checked to some extent.

       We also see in Listing above that the code responsible for generating the contract and the
       code for the implementation are  next  to  each  other.  Plugins  need  to  satisfy  those
       self-imposed  obligations  that  are  described  in  contracts.  They  ensure that plugins
       interact in predictable ways. So the process of writing individual plugins  and  composing
       them together can be described as Component-Based Software Engineering.

       Plugins  can  also  be  viewed as framework extensions. A component abstracts plugins. But
       this term is  misleading  in  our  case,  because  components  usually  can  choose  which
       interfaces  they  implement.  Elektra´s  plugins, however, are restricted to implement one
       specific interface. Without contracts, plugins could not interact  as  described  in  this
       chapter.

SEE ALSO

       •   elektra-plugins-ordering(7) elektra-plugins-ordering.md

       •   elektra-contracts(7) elektra-contracts.md

                                            July 2017                ELEKTRA-PLUGINS-FRAMEWORK(7)