OMUTEXSTREAM(3bobcat)

📦
version 6.15.01 · 7 versions
, in ubuntu stonking

💖 FBB::OMutexStream 💖

okay bestie, gather round, because we're talking about FBB::OMutexStream from the 3bobcat corner of the manual-verse, and it's giving "mutex protected std::ostream" energy, which — ngl — is exactly what it is. ✨

🌸 NAME 🌸

FBB::OMutexStream — Offers mutex protected std::ostream facilities 🫶

✨ SYNOPSIS ✨

#include <bobcat/omutexstream>

Linking option: -lbobcat

💅 DESCRIPTION 💅

okay so picture this: you're in a multi-threaded program, right? Multiple threads are all writing to the same output stream, and because context switches are a thing, the output gets all intermixed and messy. 😭 The way you prevent that is with mutexes: before writing to the output stream, you acquire a mutex lock, and you release the lock once the output is done. periodt.

OMutexStream supports writing to output streams while handling those mutex locks for you. The OMutexStream object itself is initialized with the std::ostream object that receives the information written to the OMutexStream object. This object, like std::cout and std::err usually is, is typically defined as a globally accessible object. 👑

When you insert 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. iconic behaviour, truly.

In many cases this is appropriate. Especially when statements end in newlines ('\n' or endl) this results in clean output. 💖 But 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
}
⚠️ bestie, be careful to restrict the lifetime of the object returned by OMutexStream::ostream(). do not let it hang around being all main character for longer than it needs to. 🫣

💜 NAMESPACE 💜

FBB

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

🌈 INHERITS FROM 🌈

(via OMutexStream::Out) std::ostream

🎀 CONSTRUCTORS 🎀

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

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

🔥 OVERLOADED OPERATORS 🔥

  • 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. it's giving everything std::ostream does, but with a lock. 💅
  • 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 ⭐

  • 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. 😭 she will hold the lock forever if you let her, and nobody wants that.

👑 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. (we love a clean bug list, bestie 🫶)

🌸 BOBCAT PROJECT FILES 🌸

Debian Bobcat project files:

  • libbobcat6: debian package containing the shared library, changelog and copyright note;
  • 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’. 🌈

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

🎀 AUTHOR 🎀

Frank B. Brokken (f.b.brokken@rug.nl). absolute icon, no notes. 💅

okay and that's a wrap, bestie! 💖 this lil slice of the FBB::O...xStream(3bobcat) manual ships as part of libbobcat-dev_6.15.01, dated 2005-2026. go forth and lock your streams responsibly. periodt. ✨🎀🦋

📦 where this page comes from