From 56cc59cf44ec64440ba4d1c0d005196195c758e6 Mon Sep 17 00:00:00 2001 From: hugues 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/README | 237 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 237 insertions(+) create mode 100644 dll/README (limited to 'dll/README') diff --git a/dll/README b/dll/README new file mode 100644 index 0000000..36d270e --- /dev/null +++ b/dll/README @@ -0,0 +1,237 @@ + + ============================= + 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 -- cgit v1.2.3