* Aleph - Library of utils, algorithms, data abstract types

* Version 3.0-beta

  Last update: july 2007

  New characteristics of this delivery

      - Graph support

*  Version 2.8-beta

  Last update: december 14 2004

  New characteristics of this delivery

      - Initial graphs support: linked list representation, minimal
        spanning tree algorithms (Kruskal and Prim), Dijkstra shortest
        path. These structures and algorithms are generics; they can
        be used with all graph problem whose weighs be comparables

      - First standard C++ library port (STL). *All* our tests again
        GNU STL have been winners

      - btreepic and ntreepic utils of drawing trees


* version 2.7-beta

  Last update: july 16 2003

  New characteristics of this delivery

      - Now, it is possible to use new and delete. But it is still
        preferable to use New and Delete macros

      - New memory manager.

      - New interface for binary nodes belonging to binary trees.

      - Improvements to the binary trees.

      - Dynamic binary heaps.

      - Open addressing hash tables.

      - Timer with events manager.

      - Protected hash tables.

      - IPC communication system.

      - Library fo constructing client/server distributed applications. 


*  Installation

0-. Requirements 

    Aleph has been tested on i386 Linux platforms with GCC 3.2.x and
    higher versions. Additionally, in order to compile it is required:

	- nana library. 

    nana can report compilation errors in gcc compilers 3.0.x. In order
    to avoid this, edit the nana-config.h file and defines macro
    ALWAYS_INCLUDE_MALLOC in zero. That is:

        #define ALWAYS_INCLUDE_MALLOC/* no arguments */ 0

   With recent gcc compilers, nana causes warning messages with their
   assertions. Avoid this changing

   void _I_default_handler(char *expr, char *file, int line); 

   at line 87 with

   void _I_default_handler(const char *expr, const char *file, int line);

1-. Unpacks Aleph.tbz file:

	    cd aleph
	    xmkmf

    This command will create a directory called aleph containing the
    distribution. Verify the existence of the directory and the
    existence of files. 

    Now, generate the dependences. In this way, future modifications
    will be updated by the Makefile:

	 make depend

2-. Go to distribution directory and construct the Makefile:

	    cd aleph
	    xmkmf

    After this sequence, you already must have a Makefile with which
    to build the library and to execute the examples. Verify the
    existence of the Makefile. 
    

3-. Build the library:
	    make

    This step compiles some archives and builds the library
    libAleph.a. By default, the library is built in debugging
    mode. This mode this designed to catch errors and does not perform
    the best performance. In order to build an optimized library, it
    clean all built objects and change the compilation flags:

	    make clean
	    make FLAGS="-DO3"
    

* Examples 

    The Imakefile has a very ample range of examples. Most of them
    start with the test prefix. In order to compile an example, simply
    execute:

		make testExample

    then, execute the test:

		./testExample

    Edit the Imakefile in order to add new programs or create one from
    the Imakefile of this distribution.  


* IPC

  This distribution contains the aleph ipc system. This system
  transmits efficiently ipc messages through IP networks
  (Internet). In order to use it, you must compile the demon and the
  interface library. In order to compile the demon do:

        make FLAGS="-O3 -DDEBUG -D_REENTRANT -DMEM_DEBUG" ipcDaemon

  This will compile the demon highly optimized, in debugging mode and
  with memory control. DEBUG flag specifies the debugging mode. In
  this mode, the demon deliberately will lose some network
  messages. Although this makes the protocol slower, the demon must be
  able to recover of the messages lossing without problems. The value
  of this mode is simply to verify. In DEBUG mode, many assertions are
  executed. Use the demon in DEBUG mode during the development
  stage. Eliminate this flag when you require a demon highly
  efficient.

  The MEM_DEBUG flag maintains a pool of last memory allocations. In
  this way, the signal ctr-c is intercepted to emit a memory
  report. If you suspect problems with the demon, send the output of
  this report with along your bug report. 
   
  The demon handles a log whose name is by default "log". This file
  could be very big. Use the --overwrite option in order to overwrite
  on the old logs. If you find an error, please, include the last 100
  lines of log in your bug report.

  The -s option resend the log to stdout. The --daemonize option
  daemonizes the demon. The demon becomes independent from the
  terminal and the reports are resent to /var/log.

  Type ipcDaemon --help in order to see a list of different
  options. Instance the demon in each site where you require IPC
  communication.

   In order to compile the ipc library, do:

       make libipc.a

   Link this library to each application that requires to use IPC.

  There are several demos that allow to observe the capacities of the
  IPC:

	- client.C server.C illustrates a typical application client
          server.  

	- singleClient.C multiClient.C multiServer.C singleServer.C
          illustrates the asynchronous capacities of callback,
          messages, and client server.  


* Bugs reports

  This distribution is a beta version. Many changes have been made
  from the last delivery (version 1.1). It is very possible that some
  tests do not work correctly, because these have not been intensively
  verified.

  By default, the compilation flags are configurated for reporting the
  maximum of warnings. The idea of this is to alert to beginner
  programmers. If You know exactly what you do and the warnings are
  annoying for you, then edit the Imakefile and changes the WARN
  option. Read carefully the man page of the GCC and be sure to
  understand exactly that you are deleting.

  Bugs can be reported to:

	  aleph@cemisid.ing.ula.ve         or
	  
	  lrleon@cemisid.ing.ula.ve

  If you are a student of data structures, remember that you hava a
  extra bonus by each found bug. Since this is a beta version, bugs
  are very probable.

  Part of the code of this version of Aleph has been generated by
  noweb. In general, noweb is a tool that allows literary
  programming. This means that some sources of Aleph have not been
  directly programmed in C++. In their place, these sources are
  written in a special interface and the sources C++ are generated by
  noweb. Therefore, some of the C++ sources of this distribution
  contain references to the original noweb source. For example, the
  file tpl_lhash.H contains references to the preprocessor of the
  type: 

	#line 327 "tpl_lhash.nw"

  This instructs to compiler to report errors respect to the
  tpl_lhash.nw file and not with respect to tpl_lhash.H file. The
  consequence of this is that il may be annoying to locate the
  compiler messages and to debug. The Aleph team decided to leave
  these directives because the team thinks that they facilitate the
  maintenance and the processing of bug reports. If you consider that
  this is too heavy for its work, then you can, easily, suppress these
  lines with some tool like sed, Perl, etc.


* Current bugs

      - It is sure that the descendent splay tres (tpl_splayTree.H)
        contain a bug.

      - Performance measures suggest that the randomized tres and the
        skip lists contain a bug.

* Future extensions 

  Version 3.0

	  - Graphs
	  - Extended hashing
	  - B, B+, B* trees
	  - Binomial and Fibonacci heaps
	  - STL interface on Aleph

  Version 4.0

	  - OMG CORBA support wit mapping C++, IDL compiler, ORB
            run-time and ORB deamon.

  Version 5.0 will be consecrated to run-time code generation.


* Contributors

  Aleph is the result of the effort of several people, mainly,
  students of the CEMISID.

  Aleph has been granted and supported by the CDCHT, CONICIT,
  CECALCULA and the Computer Science Department of the University of
  Andes. 

  Main contributors: 

  -. Leandro R. Leon 
  -. Vctor Bravo (skip lists, splay trees, red black trees, dynamic
     hashing) 
  -. Juan Carlos Vargas (threaded and ranked trees) 
  -. Carlos Nava (event handling, ipc system, timers) 
  -. Andrs Arcia (distributed services, daemonization) 
  -. Demian Gutierrez (mapping corba) 
  -. Juan Luis Chaves (bit Array) 
  -. Leonardo Zu~iga (treepic)
  -. Bladimir Contreras (treepic)
  -. Carlos Acosta (treepic)

