summaryrefslogtreecommitdiff
path: root/dll/MANUAL
diff options
context:
space:
mode:
Diffstat (limited to 'dll/MANUAL')
-rw-r--r--dll/MANUAL138
1 files changed, 138 insertions, 0 deletions
diff --git a/dll/MANUAL b/dll/MANUAL
new file mode 100644
index 0000000..5e7cfa0
--- /dev/null
+++ b/dll/MANUAL
@@ -0,0 +1,138 @@
+
+ =============================
+ Dynamic Library Loader Module
+ =============================
+ GLAGEN - 2002 - Hugues HIEGEL
+
+
+
+
+ I. What is it ?
+
+
+The Dynamic Library Loader Module (DLL Module) is part of the GLAGEN
+Engine. It goals is to provide to the end-user a flexible usage of
+external C/C++ libraries (*.so) .
+
+At this time, only C++ libraries are supported, because the main DLL
+Module is already written in C++. It should be easy to allow C-written
+libraries, but du to a lack of time, it should appear.. later.
+
+
+
+ II. How does it work ?
+
+
+The DLL Engine reads all libraries, especially their Names and
+Dependancies, and then builds a dependancies tree. This last would be
+used by the Network module (written by lam_m), and should determine in
+which order each library would be executed in the main loop.
+For example:
+
+ library A needs nobody, alike library B. Libraries AC and AD needs
+ A, BE and BF need B, ACG needs AC and BFH needs BF.
+ We would obtain such a tree:
+
+ (root)
+ \__________________
+ | |
+ A B
+ \_______ \_____
+ | | | |
+ AC AD BE BF
+ \_ \_
+ | |
+ ACG BFH
+
+
+ Then the execution order would be done in such an order, reading
+ the tree top-bottom and left-right:
+ A-AC-ACG-AD-B-BE-BF-BFH
+
+ Like that, we are certain that any library would be able to read
+ the results of one of its dependancies.
+
+I did a Library class that contains a lot of infos about each
+library.so. For each library file, I effectively create a new Library
+instance, and initialize it by opening the library, ang trying to get
+infos using dlsym and some canonical symbols (See section above for
+more info about libraries' symbols). If the library do answer to the
+required ones, then it is stored, else it is immediately closed and
+forgotten.
+
+Along the program, we will mainly work with list of Libraries, for
+this class is our swiss tool.
+
+
+
+ III. The Library class
+
+
+You should find prototypes & declarations in the
+./dll/classes/libclass.hh file and definitions & implementations in
+the ./dll/classes/libclass.cc file in the root of the glagen devel
+directory.
+
+The Library class mainly consists of:
+
+ a Filename string,
+ a handler void pointer,
+ and some important methods.
+
+I'll explain each method.
+
+III.1 Methods
+
+ III.1a Library(), Library(string Filename)
+These are the creators. They only create a new class.
+The one with the string also initializes the Filename property to the
+given value.
+
+ III.1b ~Library()
+The destructor.
+It cleans the Library class, although it is not really necessary in
+the measure we work on variables (not pointers),
+
+ III.1c LoadLib(), LoadLib(string Filename)
+This is one of the most important methods. It opens the file, tries to
+obtain an handler and if succeed, stores this handler in the correct
+property.
+Then we call, if found, the GLG_Hello() symbol, in which the
+devel-user should output some text in cout.. As he feels it.
+It would be called once during the whole glagen process' life.
+(Maybe two if using the network).
+This method is used to obtain infos such as Library name and
+dependancies, in order to sort it and check that no dependancy is
+missing. Elsewhere, it would tell you the name of missing libraries
+and ignore this one. And continue with next library.
+
+ III.1d Initialize()
+The great one. This method would be called once in the loading process
+to calculate data size on the server, and then another time once
+loaded in a client, to preserve an area in the data memory.
+In this method, we would ask the user library to make as many palloc()
+as it wants, each palloc, in the order, being allocating some data
+memory.
+For example:
+
+ Library Foo needs to use and/or share three sorts of data in the
+ whole glagen process, for example a surface information, a color
+ one and the age of the captain.
+ Foo should have a GLG_Init() function like this :
+
+ GLG_Init(...)
+ {
+ ...
+ palloc(surface, ...);
+ palloc(color, ...);
+ palloc(captainage, ...);
+ ...
+ }
+
+ The library class linked with this library would then ask the
+ server for some memory rooms, and then stores three (because of
+ the three palloc()) keys in some deep owned property.
+ During the main loop, the library should only ask to read or
+ write its third room to obtain or modify the captainage.
+
+ III.1e