path: root/trunk/glagen/dll/README

	=============================
	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-to-bottom, then left-to-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

In this section, I will explain the main characteristics of this class
and the method used.

  III.0 Hello, Bye

First of all, we allow the user to make two functions in its library :
GLG_Hello and GLG_Bye, in which he could put an hello and bye message
to the standard out. For example. He also could wathever he wants in
them, but no initialisation. These would be desribed in the next
chapter. Hello and Bye are there just to give flexibility and a bit of
fun.

  III.1 Initialisation

Creating a new Library class and Loading it consists in giving a
library filename, trying to open it, then trying to obtain a DL
handler.
If a handler is obtained, we load some Symbols to check if it is
a real GLAGEN library : the .so must return a name as a string in
respond to the call at GLG_Name(). Then we try to get its dependancies.
These infos are finally used to generate the dependances tree ahead.
The dependancies are given under a list of string, that make the
treatment easier.

Each library is allowed to use as many properties it wants for every
3d engine's dot. Each dot has a list of properties, and this list is
created by a recursive call of every library's GLG_Init symbol. Each
library class associated with each library file retains for each
property requested its position in the global list of properties.
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.
     It doesn't even know the captainage is really stored in some
     42nd room in the whole 'memory'.

palloc() is a function that calls itself a method of the current
calling library, so this library can stores the global acces method on
the local machine.
For that, the initialize() method gives a pointer to (this) to the
GLG_Init of the dll. Then this dll has nothing to do qith this
pointer, just give it as a parameter to palloc(). This palloc(),
defined out of the library class, calls then the REF->_palloc() method.
I didn't found a simpliest method to do that, because I didn't want
the dll developper hav to know anything about the Library class.
If I forced him to call REF->_palloc() instead of palloc(REF), he
would have to know the REF* prototype for its GLG_Init definition,
then he would have to use the libraryclass header.
My goal is to provide him a 'totally' independant code. So, I choose
to make him take a void* REF in its GLG_Init(), and then give this 
void* REF to palloc, which takes it as a Libary*.
See code for more details : ./dll/classes/libclass.hh and a sample
library code.


  III.2 Global properties accesses

Two functions allow libraries to access dots properties, in read or
write mode. 
For example:

    Library17 has 3 dots properties, declared in order (the 1st in
    first place, the 2nd in second place and the 3rd in last). 
    The library's user know what is the first property, what is the
    second, and what is the third. For example, he decides the first
    property is the color, the second the height, and
    god-know-whatever is the third. When he wants to access the color
    property, he would only call a GLG_read(2, ...) function.
    This function will then call a method of the current class to get
    the REAL position of this 2nd element in the whole list of
    properties, shared by many other libraries..
    And then, the access of the '2nd' element would be transparent to
    the user.

There is also a GLG_write function based on same principle. They both
looks like read and write standard C functions, which is absolutely
natural.

The main difficulty of these functions were that I didn't know in
which level the efficient read and write should be done. In the
library engine ? In which level ? Client-side ? Server-side ? If
ti is in Client-side, how would the server know ? If it is in
Server-side, how would the Client know ??

So, we decided to keep one dot property tab in each computer (clients
and server), make all inits, reads and writes in the local computer.
A first initialisation is made in the server, to know the global size
of a dot property tab. Then a second is done in each client, which
returns to the server the total size found. Then the server knows what
it will allocate for each client.
Example:

    The server loads libraries A, AC and B. A needs 4 bytes, AC needs
    3, and B needs 5. The server knows that A and AC will be sent to
    the client1. Then he allocates 4+3 then 7 bytes to client1, and
    the 5 last bytes to client2. Client1 receives A and AC, reads them
    and finds 7 bytes to allocate locally. Client2 will find 5 bytes
    to allocate locally. After each main loop, client1 will send its 7
    bytes to the server, who will put them in right place. Client2
    sends its 5 bytes, and the server puts them in back of the 7 first
    bytes.

That is trivial. Although this is the network part, I did the routine
to make that. The source code can be found in
create_dotproperty_init.cc file. It has to be included in right place
in the clients and server main functions.


  III.3 Main loop

Not yet fully implemented.
The main loop call is called GLG_Main, and would take as argument a
Dot* pointer. Then the user has to include the dot.hh header, found in
the 3d engine directory or in the ./classes folder.
In this main loop, the user just has to read and write properties in
the given Dot. The time and other dot-independant informations should
be given in a method that has not really been specified at this time.
The read function calls should be done specifiying a library name, and
the result will be given only if the current library has read access
to the given one. There, the dependancies takes all its meaning. 
But why would we do more processing by checking the permissions ? This
permitts Glagen to be a clean processus.
However, a library could read its dependancies properties and
recursively the dependancies of its dependancies. That would look more
natural in this way.
Note that there are two 'system' properties, such as primary color and
primary height of the dot. 'Primary', because one 'dot' should
represent superposed surfaces' dots.
Finally, some Perlin noise functions should have been given in this
level, allowing the user to make realistic world renderings.
Just see the sun example in our website to be convinced ;)


       IV. Conclusion

This part is not yet finished, due to some difficulties to understand
how would my module work in the global project. The mainloop call
is not realy finished, but some minor changes have to be done. 
The main squeletton is already the module itself, so I am globally
satisfied about my work, although I would be more satisfied if it were
really included in the final project.
Since it is under GPL, I would not abandon it. I spent too much time
on it to give forfeit. Without the pressure of the school, I would
certainly end my module and best it in great state of spirit.

The main reason, I think, that I didn't finish my part in time, is
that I spent to much time on making a clean code. A program that
doesn't bug without reason. This is the most important to me.
If I made a code in the only goal to make a finished product, I would
certainly hav missed lots of bugs, and the final result code would
have been so awful I would never continue it.
did