src/kmscon_module.h

   1 /*
   2  * kmscon - Module handling
   3  *
   4  * Copyright (c) 2012-2013 David Herrmann <dh.herrmann@googlemail.com>
   5  *
   6  * Permission is hereby granted, free of charge, to any person obtaining
   7  * a copy of this software and associated documentation files
   8  * (the "Software"), to deal in the Software without restriction, including
   9  * without limitation the rights to use, copy, modify, merge, publish,
  10  * distribute, sublicense, and/or sell copies of the Software, and to
  11  * permit persons to whom the Software is furnished to do so, subject to
  12  * the following conditions:
  13  *
  14  * The above copyright notice and this permission notice shall be included
  15  * in all copies or substantial portions of the Software.
  16  *
  17  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  18  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  19  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  20  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
  21  * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
  22  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  23  * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  24  */
  25
  26 /*
  27  * Module Handling
  28  * Several subsystems of kmscon provide a generic interface that is implemented
  29  * by different backends. The user can choose a backend that is then used.
  30  * To make out-of-tree development easier and, more importantly, to reduce the
  31  * direct dependencies to external libraries, this subsystem implements a
  32  * dynamically-loadable module system.
  33  *
  34  * Modules can be loaded and unloaded during runtime. A module basically
  35  * provides memory-storage for code. As long as any code of a module is still
  36  * used (that is, registered as callback) we must not unload the module.
  37  * Therefore, we use reference-counting to allow other subsystems to acquire and
  38  * release code sections.
  39  *
  40  * A module needs to provide "module_init". Everything else is optional.
  41  * "module_init" is called after the module has been loaded and should
  42  * initialize the module. "module_exit" is called after the module has been
  43  * unloaded and the last reference to the module has been dropped. Therefore, it
  44  * is safe to release all allocated resources in "module_exit".
  45  *
  46  * "module_load" is called after "module_init". A module should register its
  47  * resources here. "module_unload" is called when the module is scheduled for
  48  * removal. A module should unregister its resources here. However, it must not
  49  * release the resources as there might still be users of it. Only when
  50  * "module_exit" is called, kmscon guarantees that there are no more users and
  51  * the module can release its resources.
  52  */
  53
  54 #ifndef KMSCON_MODULE_H
  55 #define KMSCON_MODULE_H
  56
  57 #include <stdlib.h>
  58
  59 struct kmscon_module;
  60
  61 int kmscon_module_open(struct kmscon_module **out, const char *file);
  62 void kmscon_module_ref(struct kmscon_module *module);
  63 void kmscon_module_unref(struct kmscon_module *module);
  64
  65 int kmscon_module_load(struct kmscon_module *module);
  66 void kmscon_module_unload(struct kmscon_module *module);
  67
  68 void kmscon_load_modules(void);
  69 void kmscon_unload_modules(void);
  70
  71 #endif /* KMSCON_MODULE_H */