---
name: "omutexstream"
section: "3bobcat"
platform: "linux"
package: "libbobcat-dev"
version: "6.07.01-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/omutexstream"
---

# omutexstream(3bobcat)

Offers mutex protected std::ostream facilities

## 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)](/bobcat/7.md)

## BUGS

None Reported.

## BOBCAT PROJECT FILES

- o

  *https://fbb-git.gitlab.io/bobcat/*: gitlab project page;

Debian Bobcat project files:

- o

  *libbobcat6*: debian package containing the shared library, changelog and copyright note;

- o

  *libbobcat-dev*: debian package containing the static library, headers, manual pages, and developer info;

## 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**).