|
|||
User documentation
Introduction.The dependencies between Epeios libraries look like a tree. It means that only some libraries are written from scratch (i.e. only using the standard C/C++ or OS specific libraries). Most Epeios libraries are based on other Epeios libraries. Because this libraries are Free Software, you have only to take a look on their sources to see examples on how to use them. By the way, take notice that all software and libraries from the Epeios project are under GNU GPL. Taking a look to the QuickDoc may be very helpful.Most of the library do not fully implements the concept they deal about because they are written to be used by another library, so it does generally only implements what needed by this library. However, they are designed so that they can be easily completed, and this would be do in the future. Most of the Epeios libraries are designed so they can be used on each system which have a C++ compiler, because this particular libraries use only the C(++) standard libraries. Some other Epeios libraries, which deals with more OS specific concept, like socket, pipe, shared memory, multitasking, etc., work only under UNIX and Windows, that's because this OSes are the only ones that I have access to. This means that, if you write software making use of such libraries, they actually work only on UNIX and Windows systems. But, as soon as this libraries are adapt to other systems, your software would work, without modifying the sources, on this other systems. The Makefiles are designed for GNU Make (check here for miscellaneous port). To work, two enviroment variables must be defined. The first, EPEIOS_OS, must be set to linux under GNU/Linux and windows under Windows. The second one, EPEIOS_SRC must contain all the needed source directories separated by : under GNU/Linux and ; under Windows and without an ending / or \. Under GNU/Linux, the libraries were tested with GNU GCC V2.95.2. Under Windows, BC++ can be used, but, due the limitation of the length of a command line under some Windows version, some Makefile don't work properly on linking. Both compiler are available for free. Concerning GNU/Linux, I test the libraries/software on a Intel/x86 system, but I occasionnaly test them on other GNU/Linux system (Apha, PPC and SPARC), and they seem to work without problems. Principles.Object types.Static objects.Objects of this type are of fixed size. They are based on the C(++) fundamental types like integer, char, float, double, ..., which are also considered as static objects. Some more OS specific types, like handler or file descriptor, which are usually based on fundamental C(++) types, are static objects too. Any object constituted only by static objects is a static object too. Dynamic objects.Objects of this type have a size which can be modified. They remain dynamic objects even if they contain one or more static objects. The heart of such an object is constituted of a set of static objects (see the SET library), or a set of dynamic objects (see CTN library). Objects which are constituted by one or more dynamic objects are dynamic objects too. Memory handling.In the Epeios libraries, the memory isn't use the usually way. If you have to store some object, you have, almost always, to use a memory object. You don't have to work directly with such an object, but many Epeios libraries use such an object. By default, memory objects use RAM (or what ever the OS use for it) as memory. But you can use a file, for example, as memory.Once the memory type chosen, the different memories have the same functionalities and can exchange their data. Flow handling.A flow is an object from which you can read sequentially what you write in it, sequentially, before. It's like a pipe (or a stream). Flows are used in many situation. For example, to write to the standard output, to write/read to/from a file, for communication between machines or thread, etc. Such a flow is divide in 2 part. One part is to write in, the other to read from. They respectively called 'output flow' and 'input flow'.Writing an object.To be correctly handled by the object management libraries, there is no constraints for a static object, as long as it follows the static objects specifications.For the dynamic object, you have to respect following rules.
As you can see, all this functions are serializations functions. To follow the Epeios project rules, you have to append a _ to the name of the object. To obtain the instantiable version of this object, write AUTOx( T ) , where T is the name of the object (without the appending _). Put 1, 2, or 3in place of the x if this objects is a template object with respectively 1, 2 or 3 template parameters. Don't put the x if the object is not a template object. Error handling.The Epeios libraries implements its own error handling system. With this system, you write your program without taking care of errors which can occur (except errors due to wrong user entry).By default, an error prints the type of the error, and the incriminated file and line ; this is very useful during for debugging. Once the program debugged, you have to put the appropriate error handler. There is usually not very much to do. The ERR library (ERRor).The context macros.You have to use them in the function which instantiates a dynamic object or a static object with destructor. Such a function have the following structure (the name, input and output values are only examples):int foo( void )
{
1
ERRProlog
2
ERRBegin
3
ERRErr
4
ERREnd
5
ERREpilog
6
}
If you proceed so, it's guaranteed that the destructor of the objects declared at part 2 are called, whether or not an error occurs. Of course, you don't have to use this macro in all your functions. Only functions which creates objects with destructors need them. Functions which uses objects are passed as parameters, or declared in the object, if this function is a method, doesn't need this macros. The status macros.This macros are generally used when an error occurs, to have details about this error. The ERRMajor give the major number of the error, which indicates what type of error occurred, and it correspond to a err::type value.The ERRminor give the minor number of the error. It corresponds to the err::xxx type, where xxx is the corresponding error type given by ERRMajor. The ERRMessage() return a descriptive message about the last occurring error if no parameter given ,or about error corresponding to the given parameters. The memory libraries.Memory drivers.The MDR library (Memory DRiver).This library provides a base class with virtual functions. You don't have to use it directly, but the memory libraries listed below overload it. All the memory drivers can be used by a dynamic object by giving it to its appropriate plug() function. The CVM library (ConVentional Memory).This library provides a memory driver which uses conventional memory (RAM, or what ever the OS use for it). The FGM library (FraGmented Memory).Same as the CVM library, but allocates memory blocks of fixed size, which are usually not contiguous. Was written for use with DOS program, in which you cannot allocate more then 64k of contiguous memory. The FLM library (FiLe Memory).Provides a memory driver which uses a file to store data. You can give a file name at initialization, or let the library generating one. You can also tell to this memory not to delete the file when the object destructed, so the same object can be used the next time you launch the program, or by another program. The MMM library (MultiMeMory).This library provides a memory driver which allows to manage several memories in one. To store an dynamic object, which contains several objects, using files, you normally need as many files as contained dynamic objets. Thanks to the MMM library, it's possible to store all the objects in one file. To do this, you create a mmm_multimemory with the wanted type of memory (the CVM is the default one), and you give it to the object by calling the plug() function (as you do for dynamic objects). Once configured (calling the plug() function to use another memory type as the default one) and initialized, you can give it to an object which provides the appropriate plug() function (all dynamic objects should provide this function). The MMI library (MultiMemory Indexator).To use a memory in a multimemory memory, you have to store a value which refers to this memory (like the value returned by the C function malloc()). If you change the size of this memory, the value can change (like the value returned by the C function realloc()). With the memory driver provided by this library, you can refer to a memory in a multimemory by using one value, which never change from the creating to the freeing of this memory. Memory libraries.The UYM library (UntYped Memory).With this object, you can allocate room to store bytes. Within the allocated room, you can read or write one or more bytes. You can adjust the size of the allocated room whenever you want. By default, the bytes are stored in RAM (it uses the memory driver provided by the CVM library). But, by giving another memory driver (with the plug() function) you can use another type of memory, like one described in the previous 'Memory drivers' chapter . You can copy part or all of a untyped memory in another untyped memory, even if they don't use the same memory driver. The TYM library (TYped Memoty).Same as untyped memory (UYM library) but it handles, through a template parameter, static objects rather then bytes. And you can only exchange data between memories which handle same static objects type. The object management libraries.General.The BCH library (BunCH).Provides an object named BUNCH(t). t is the type of static object which the BUNCH object have to store. Same as the typed memory (TYM library), but this object knows its size. So, you can easily append objects and copy all or part of one set (of same static objects) in another. The CTN library (ConTaiNer).Provides a object named CONTAINER(t). Many variation are provided. Objects called ITEM are provided to deal with an item of the containers. Same as the BCH library, but t is a dynamic object. And, because a CONTAINER library is designed like a dynamic object, you can store containers in containers. The BITBCH library (BIT BunCH).Conceptually, the BITBCH library provides an object which is a BUNCH (from the BCH library) of bits. We had to create a special object, because BUNCHs can only store static objects with a minimal size of one byte (8 bits). For each bit, 8 bits would necessary. The BITBCH library was designed to avoid the loss of so much room. It has the same functionalities as a normal BUNCH. Further reference to the BCH library would also refer to this library too. Conclusion
The MMG library (Memory MerGing).We have seen that we can use a file to store an object. It seems logical that it should be possible to create persistent object, which survive to the program which create it. So, the next time you launch the program, it have not to reconstruct the same object, but only to recover the one stored on the disk.This is not possible by using only the file memory driver (FLM library), because there is only the data of the object which is stored in the file. To use it, it lacks on some data, like the room used by the object. Without this data, you can not use the object. Although the dynamic part of the object is stored in the file, the static part, which contains, for example, the size of the object, is stored in RAM, and so loss once the software stopped. The MMG library provides an object in which both the static part and the dynamic part are stored in the memory, so it's easy for a program to recover this object, even if it doesn't create it. The flow related libraries.The FLW library (FloW).This library provides the base class for all the flows. It allows that all the following flow libraries can be handled the same way, once initialized.In addition, it provides the fout, fin and ferr flows which replace respectively the standard C++ cout, cin and cerr streams. The SCK library (SoCKet).This library provides a flow driver based on sockets, which allows communication between different computer connected to the same network, like Internet.The PIP library (PIPe).It's current that more that one process shared the same flow. For example, in case of several client processes all communicating with the same server process. This usually occurs through a pipe.This library, which extends the PIP library, ensures that no more that one process at once can be access to the same pipe end. Like the PIP library, it provides a flow driver. The ordering libraries.Introduction.To store data, you use a BUNCH or a CONTAINER. But the data are stored in a linear way. And they are difficult to manipulate. For example, to suppress one data, you have to shift all the following data down, and to adjust the size of the storing object.If there is a way to handle this object by itself like a stack or a queue, this is not possible for more complex structure, like trees. In addition, you want probably to use structures which all deal with the same data, but in different orders, like indexes in databases.An object is stored at a certain position in the a BUNCH or a CONTAINER. The corresponding information for this object are stored in the different structure handling library at the same position. An object is stored at a certain position in the a BUNCH or a CONTAINER. The corresponding information for this object are stored in the different structure handling library at the same position. You can attach as much such structures as you want to a BUNCH or a CONTAINER. the LST library (LiST).This library provides an object which allows to handle a list of object. you have to overload the LSTAllocate() function, and then you can add/suppress object without carrying about the room needed.When you suppress an item, the LST library store its position to use it again when a new item is needed. If there is no free room to store an object, new room is automatically allocated. This library is useful if you want to quickly add/remove items of a set, when the order of the items doesn't matter. If you only add items, the order reflects the order in which you add them. The STK library (StaCK).This library provides an object which handle the usual PUSH and POP functionalities which go along with the stack concept.The QUE library (QUEue).This library provides a object which allows to organize data in a queue structure.The BTR library (Binary TRee).This library provides a object which allows to organize data in a binary tree.The IDXBTR library (InDeX Binary Tree).This library provide an index based on binary tree. It's a good index for sorting, but not the fastest for scanning.The IDXQUE library (InDex QUE).This index provides an index based on queue. It's fast for scanning, but slow for sorting.The IDXBTQ library (InDex Best of Tree and Queue).This library provides an index which implements both binary tree index and queue index. So, it's fast for both sorting and scanning.The socket related libraries (for use with the SCK library).Introduction.As written before, the SCK library provides a flow driver based on sockets. But it needs a sck__desc object at initialization. This object is provided by the 2 libraries below.The CLT library (CLienT).This library allows to open a connection to a computer through its IP adresse an port (www.epeios.org:http format or 212.95.72.3:80 format). You obtain then a sck__desc object that you can give to the SCK library to communicate with the computer through a flow, or with the SCKRead()/SCKWrite() functions.This is the client part of a client/server architecture. The SRV library (SeRVer).This library listen to a port and return a sck__desc object the incoming connection. you can then use this sck__desc object with the SCK library.This library also provides an object which calls a virtual function, that you have to overload, in its own process each time a new connection is detected. This is the base of the server part of a client/server architecture. Frontend/backend related libraries.IntroductionThe Epeios project provides libraries, detailed below, that implements a specific backend/frontend relation mechanism. The communication between the 2 parts is based on flows.It's, of course, possible to run both part in one process, and alosi, thanks to the PIP library, to run each part in it's own process, communication occurring between the 2 part through pipes. You can even run the frontend on a computer and the backend on another by using the socket implementation of the flow (library SCK). One broker accessed simultaneously by several frontend. The CSM library (Client/Server Manager).This library is one of the powerfullest library of the Epeios project. All the SCK, SRV, MTK, PIP, SPP, SPH, SHM were formerly written to be used by this library.This library allows to write a server application, i.e. a program which runs on a server machine, and which handle all connection from client machine. The principle is to have one client process per connection (from a client machine) which all communicates with the same server process. The exchanges between the client machine and its client process, and the exchanges between the client processes and the server process both occur through flows (FLW library). You have only to provide the functions for the client processes and the server process. The SALCSM library (Stand ALone CSM).NOTA: CSM refers to the so-named library.The CSM library allows several frontends to access to the same broker, broker and frontends running, each, on a different computer, or, at least, in different processes. But you want surely to run your application on a more conventional way, i.e. one backend and one frontend on the same computer, and using one process for both. This library allows this, without modifying the heart of you application. Frontend and backend communicate using the memory, not pipe nor sockets. This library is also useful for debugging applications designed to be using the CSM library, because all the application runs in the same thread/process. Miscelleanous.The SHM library (SHared Memory).This library provides functions to handle shared memory, i.e. memory that can be shared between several process.The SPH library (SemaPHore).This library deals with semaphores.The STR library (STRing).This is the implementation of the string concept, which is based on the BUNCH library. It's a good example on how to use this library and to see the structure of a dynamic object.The MTK library (MultiTasKing).Allow to launch a user function using a new process. The calling function and the called function run then together and simultaneously in different threads/processes. |
|||
|