From 56cc59cf44ec64440ba4d1c0d005196195c758e6 Mon Sep 17 00:00:00 2001
From: hugues <hugues@0f7e0d06-a6f9-0310-a55f-d5f984f55e4c>
Date: Sat, 25 Mar 2006 15:07:51 +0000
Subject: Nettoyage du repository glagen

git-svn-id: file:///usr/local/opt/svn/repos/glagen@12 0f7e0d06-a6f9-0310-a55f-d5f984f55e4c
---
 dll/MANUAL | 138 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 138 insertions(+)
 create mode 100644 dll/MANUAL

(limited to 'dll/MANUAL')

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    
-- 
cgit v1.2.3