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)