focal (3) omutexstream.3bobcat.gz

NAME

       FBB::OMutexStream - Offers mutex protected std::ostream facilities

SYNOPSIS

       #include <bobcat/omutexstream>
       Linking option: -lbobcat

DESCRIPTION

       In  multi-threaded  programs  output  written  by  different  threads  to  the  same output stream may be
       intermixed due to context switches. This is prevented by using mutexes:  before  writing  to  the  output
       stream a mutex lock is acquired, releasing the lock once the output is completed.

       OMutexStream  supports  writing to output streams while handling the mutex locks. The OMutexStream object
       itself is initialized with the std::ostream object to receive the information written to the OMutexStream
       object. This object, like std::cout and std::err usually is defined as a globally accessible object. When
       inserting information into the  OMutexStream  object  OMutexStream  first  returns  an  OMutexStream::Out
       object, whose constructor locks the OMutexStream::Out mutex. The OMutexStream::Out object’s lifetime ends
       at the end of the insertion statement, and at that time its destructor releases the lock.

       In many cases this is appropriate. Especially when statements end in newlines (’\n’ or endl) this results
       in  clean  output.  In  some cases this approach doesn’t work. Consider the situation where the output is
       produced by a series of iterations in a for-statement. For these cases  OMutexStream  offers  the  member
       ostream returning an OMutexStream::Out object. As that object also locks the mutex, the lock also remains
       active during its lifetime. During its lifetime  separate  OMutexStream  insertions  expressions  may  be
       executed. E.g., the following code fragment will complete all output forcing competing threads to wait:

           void fun()
           {
               OMutexStream mout{ std::cout }; // create an OMutexStream object
               {
                   auto out{ mout.ostream() }  // locks the mutex (lock #1)
                   mout << "Hello ";           // also locks (lock #2, at ;
                                               //             back to lock #1)
                   out << "world\n";
               }                               // ’out’ releases the lock
           }

       Be careful to restrict the lifetime of the object returned by OMutexStream::ostream().

NAMESPACE

       FBB
       All  constructors,  members,  operators  and manipulators, mentioned in this man-page, are defined in the
       namespace FBB.

INHERITS FROM

       (via OMutexStream::Out) std::ostream

CONSTRUCTORS

       o      OMutexStream(std::ostream &out):
              The OMutexStream object is initialized with an std::ostream object.

       Copy and move constructors (and assignment operators) are available.

OVERLOADED OPERATORS

       o      OMutexStream::Out operator<<(OMutexStream const &mstr, Tp &&tp):
              This member is a function template. Its forwarding reference is passed on to the OMutexStream::Out
              object constructed by mstr. Since OMutexStream::Out constructors lock the class’s mutex, and since
              OMutexStream::Out was derived from std::ostream  all  insertion  and  other  operations  that  are
              allowed for std::ostream can also be used for OMutexStream::Out objects.

       o      OMutexStream::Out operator<<(OMutexStream const &mstr, Ret &(*manip)(Ret &os)):
              This  member  also is a function template. It is used for inserting manipulators without arguments
              into OMutexStream::Out objects.

MEMBER FUNCTIONS

       o      OMutexStream::Out ostream() const:
              A OMutexStream::Out object is returned that has locked its mutex, and will keep  the  lock  during
              its   lifetime.   All   functionality  of  the  std::ostream  class  can  also  be  used  for  the
              OMutexStream::Out object returned by ostream.

              Be careful to restrict the lifetime of the object returned  by  OMutexStream::ostream()  to  avoid
              needlessly long mutex locks.

EXAMPLE

       #include <iostream>
       #include <thread>
       #include <chrono>
       #include <cstdlib>
       #include <cmath>
       #include <ctime>

       #include <bobcat/omutexstream>

       using namespace std;
       using namespace FBB;

       OMutexStream mout(cout);

       void run(int nr)
       {
           for (size_t idx = 0; idx != 3; ++idx)
           {
               mout << "hello world 1 from thread " << nr << ": " <<
                       log(rand()) << endl;

               this_thread::sleep_for(
                       chrono::milliseconds(200 + rand() % 800));

              mout << "hello world 2 from thread " << nr << ": " <<
                       log(rand()) << ’\n’;

               this_thread::sleep_for(
                       chrono::milliseconds(200 + rand() % 800));
           }

           auto out{ mout.ostream() };
           cout << nr << ": " << out.tellp() << ’\n’;
       }

       int main()
       {
           srand(time(0));

           thread t1(run, 1);
           thread t2(run, 2);
           thread t3(run, 3);
           thread t4(run, 4);

           t1.join();
           t2.join();
           t3.join();
           t4.join();
       }

FILES

       bobcat/omutexstream - defines the class interface

SEE ALSO

       bobcat(7)

BUGS

       None Reported.

DISTRIBUTION FILES

       o      bobcat_5.02.00-x.dsc: detached signature;

       o      bobcat_5.02.00-x.tar.gz: source archive;

       o      bobcat_5.02.00-x_i386.changes: change log;

       o      libbobcat1_5.02.00-x_*.deb: debian package holding the libraries;

       o      libbobcat1-dev_5.02.00-x_*.deb: debian package holding the libraries, headers and manual pages;

       o      http://sourceforge.net/projects/bobcat: public archive location;

BOBCAT

       Bobcat is an acronym of `Brokken’s Own Base Classes And Templates’.

COPYRIGHT

       This is free software, distributed under the terms of the GNU General Public License (GPL).

AUTHOR

       Frank B. Brokken (f.b.brokken@rug.nl).