libthreadar Code

                        L I B T H R E A D A R
			---------------------
			    -------------
			        -----





What is libthreadar?
        libthreadar is a library providing a set of C++ classes for manipulating
	threads and propagating back exception from thread to parent thread when
	the parent calls the join() method.

What is it relying on?
        libthreadar relies on Posix thread for historical reason, this might
        change in the future to rely on C++11 thread without any impact on
        the API.

Which compiler to use with libthreadar?
        To propagate exception of any type libthreadar use C++11 specific
        construction, so it requires such compiler to be compiled and linked
        with.

Why that strange name?
        libthreadar has been extracted from code initially part of webdar and
        also now used by dar and libdar, where from its "dar" ending name.
        However this library is not part of webdar, libdar or dar, is
        released separately and can be used independently of them.

Example of use

        class my_thread: public libthreadar::thread
        {
            public:
                    // class constructor
                my_thread(unsigned int t = 5) { secs = t; };

                    // example method to setup the thread before (re)running it
                void set_time_to_wait(unsigned int t) { secs = t; };

            protected:
	           // This method is inherited from class libthreadar::thread
		   // and is the only one mandatory to implement in your class.
                   // It contains the code that will run in a separated thread
		   // when the libthreadar::thread::run() method will be called.
                virtual void inherited_run() override { sleep(secs); };

           private:
                unsigned int secs;
        };

        my_thread t1(10), t2, t3;

	    // we modify the object after its creation but before the thread has been run
        t2.set_time_to_wait(20);

            // each of the following run() call returns almost immediately:
        t1.run();  // this fires the first thread which sleeps 10 seconds before it ends
        t2.run();  // this runs the second thread, it sleeps 20 seconds
        t3.run();  // last, this runs the third thread, which sleeps 5 seconds

        t1.join(); // the call will wait ~10 seconds for t1 to complete
        t2.join(); // should wait ~10 seconds more for t2 to complete its 20 seconds sleep
        t3.join(); // should return immediately as t3 has already finished its 5 secs sleep

            // a thread object can be run at will several times without having to reset
            // the possibly many parameters it requires to execute:

        t3.set_time_to_wait(100);

        t1.run(); // keeps secs field equal to 10
        t2.run(); // keeps secs field equal to 20
        t3.run(); // modified secs field set to 100

        t1.join(); // join() can propagate exception thrown from within the thread
        t2.join(); //        that lead the thread to end.
        t3.join(); //


Libthreadar advantage summary
          - your C++ Class inheriting from libthreadar::thread provides a shelter for
            thread dedicated data as private fields.
          - your C++ Class can provide many simple methods to setup the thread parameters
            rather than a long list of parameters provided to a function.
          - Over time it is easy to have a thread class getting new features without breaking
            backward compatibility as it is just a matter of adding new methods beside the others
            and setting default values/behavior for those new ones at object construction time.
          - private/protected fields of the class can also hold mutex, semaphores, conditions
            and other constructs to setup communication channels with the running thread, all
            wrapped in public methods for the outside world be able to communicate with the thread
            without having to know the implementation.


Libthreadar Licensing
        Libthreadar is released under the

                GNU LESSER GENERAL PUBLIC LICENSE.

        For details about this library license see the
        COPYING and COPYING.LESSER files.

Download
        You can download from GIT repos at github and sourceforge but you will need
        the auto-tools (automake, autoconf, libtool...) to create the configure
        script. You can instead download ready for use source code (having an
        the configure script built) from sourceforge:

           https://sourceforge.net/projects/libthreadar/files/

        You will find signature beside those packages, see the "Authentication"
        paragraph at http://dar.linux.free.fr/ for signature validation.
	No binary package is provided for any distro, ask your preferred disto
	maintainers if needed.

Detailed API documentation is available online at

          https://libthreadar.sourceforge.net/

        it is built from Doxygen comments found in source code