Dwm Class Library

Table of Contents

• Introduction
• History
• Platforms
• A small sample of what's in libDwm
  • I/O - Serialization
  • UnitAssert - A trivial unit testing framework
  • Dwm::SysLogger - decorated syslogging

Introduction

This class library is just a (somewhat random) collection of classes I've developed over the years for various applications. Since these are used in a variety of places, they're collected here to make reuse easy.

There are a few classes herein that I've used on nearly every software project in the last 20 years. One of those would be the Dwm::SysLogger class with the Syslog() macro, since syslogging is a common need. Another would be the Dwm::Assertions class with the UnitAssert() macro since I almost always write unit tests as part of my development process. And when I need to store data, I use the IO classes along with the various Readable and Writable interfaces.

Since much of the software I've written in the last 20 years has been multithreaded, I have also made heavy use of the Dwm::Thread::Queue class for inter-thread communication (usually as 'work queues').

History

I started this library in 1998. I continue to maintain it for my personal use. While it has grown over the years, the most common use features have been stable for a long time. To some extent they have to be stable; I have over 500,000 lines of code in my personal software repository, and a decent amount of it is dependent on this library. The good news is that those dependencies don't prevent me from refactoring, improving and growing libDwm as needed.

Platforms

I really only maintain support for 4 platforms: FreeBSD, macOS, desktop linux and Raspberry Pi OS. FreeBSD is my operating system of choice for servers and macOS is my operating system of choice for desktops and laptops. I have several Raspberry Pis I utilize for simple small tasks, and Ubuntu VMs and Ubuntu workstations.

A small sample of what's in libDwm

I/O - Serialization

Dwm::DescriptorIO, Dwm::FileIO, Dwm::StreamIO, Dwm::ASIO, Dwm::GZIO and Dwm::BZ2IO provide serialization for intrinsic types, containers of intrinsic types, user types which implement the required interfaces, and containers of these user types.

Intrinsic integer types are written in network byte order. The library takes care of byte ordering so you need not be concerned with it. Float and double types are written in IEEE 754-1985 form (see RFC 1832). Some types are stored as (length,value) pairs, including the standard containers and C++ string objects.

For user types, the required interfaces are *Readable and *Writable, such as Dwm::StreamReadable and Dwm::StreamWritable. The required interfaces for Dwm::GZIO are Dwm::GZReadable and Dwm::GZWritable. The required interfaces for Dwm::BZ2IO are Dwm::BZ2Readable and Dwm::BZ2Writable.

Note that inheritance from the aforementioned interface classes is no longer required, and is in fact discouraged. Today, the Dwm::*IO classes use concepts instead. You'll see these concepts at the top of the various *IOCapable.hh header files, which just express the same interface requirements as the pure virtual classes. This allows the library user to avoid inheriting from the pure virtual classes.

I wrote most of this functionality in 2004 when we didn't have a lot of options to support serialization. I finalized most of it in 2007 with the addition of cleaner code for std::tuple. I couldn't do this effectively until the compilers and standard libraries were up to speed. With C++11 and beyond, I was able to simplify some of the code thanks to things like variadic templates. Given that we now have C++23 and still no reflection, this work has paid big dividends for me.

Why did I spend time on this functionality? I frequently need to do things like this (error checking absent for the sake of brevity):

#include <fstream>
#include <map>
#include <string>
 
#include "DwmIpv4Address.hh"
#include "DwmStreamIO.hh"
 
int main(int argc, char *argv[])
{
  std::map<Dwm::Ipv4Address, std::string>  hosts;
  
  //  Read hosts from an ifstream
  std::ifstream  is("/tmp/hosts");
  
  if (is) {
    Dwm::StreamIO::Read(is, hosts);
    is.close();
  }
 
  //  Do something with hosts, then...
  
  //  Save hosts to an ofstream
  std::ofstream  os("/tmp/hosts");
  if (os) {
    Dwm::StreamIO::Write(os, hosts);
    os.close();
  }
 
  return 0;
}
 
 

While this is a trivial example, I've used this functionality in much more complex scenarios. Having this type of functionality in my toolbox has saved me large amounts of development time. It's reasonably flexible without a lot of extra work. No work at all if you're using types already supported. Containers of containers of supported types, for example:

#include <fstream>
#include <map>
#include <set>
#include <string>
#include <vector>
 
#include "DwmStreamIO.hh"
 
using namespace std;
 
int main(int argc, char *argv[])
{
  if (argc > 2) {
    vector<map<string,set<string>>>  data;
 
    //  Read data from an ifstream
    ifstream  is(argv[1]);
    if (is) {
      Dwm::StreamIO::Read(is, data);
      is.close();
    }
 
    //  Do something with the data...
 
    //  Then save to an ofstream
    ofstream  os(argv[2]);
    if (os) {
      Dwm::StreamIO::Write(os, data);
      os.close();
    }
  }
 
  return 0;
}

Since the library handles C++ <tuple>, you can create new data classes and easily add serialization by keeping all of your class's data in a tuple. Below is a trivial contrived example of a phone contact data store. The serialization members required are lines 44 to 49 and 110 to 115. These are easy to implement, since they each require only a single call to a member of an I/O class. Note that I never put  using namespace std in header files. It's here just to reduce clutter on your screen.

#include "DwmDescriptorIO.hh"
#include "DwmFileIO.hh"
#include "DwmStreamIO.hh"
 
using namespace std;
 
//----------------------------------------------------------------------------
//----------------------------------------------------------------------------
class PhoneContact
{
public:
  PhoneContact() : _data() { }
 
  const string & FirstName() const  { return get<0>(_data); }
  const string & FirstName(const string & firstName)
  {
    get<0>(_data) = firstName;
    return get<0>(_data);
  }
 
  const string & LastName() const  { return get<1>(_data); }
  const string & LastName(const string & lastName)
  {
    get<1>(_data) = lastName;
    return get<1>(_data);
  }
 
  const set<pair<string,string> > & PhoneNumbers() const
  { return get<2>(_data); }
  bool AddPhoneNumber(const string & phoneName,
                      const string & phoneNumber)
  {
    pair<string,string>  phone(phoneName, phoneNumber);
    return get<2>(_data).insert(phone).second;
  }
 
  bool RemovePhoneNumber(const string & phoneName,
                         const string & phoneNumber)
  {
    pair<string,string>  phone(phoneName, phoneNumber);
    return (get<2>(_data).erase(phone) == 1);
  }
  
  istream & Read(istream & is) { return Dwm::StreamIO::Read(is, _data); }
  ostream & Write(ostream & os) const { return Dwm::StreamIO::Write(os, _data); }
  ssize_t Read(int fd)             { return Dwm::DescriptorIO::Read(fd, _data); }
  ssize_t Write(int fd) const      { return Dwm::DescriptorIO::Write(fd, _data); }
  size_t Read(FILE *f)             { return Dwm::FileIO::Read(f, _data); }
  size_t Write(FILE *f) const      { return Dwm::FileIO::Write(f, _data); }
 
private:
  tuple<string,                     // first name
        string,                     // last name
        set<pair<string,string> >   // phone numbers
        > _data;
};
 
//----------------------------------------------------------------------------
//----------------------------------------------------------------------------
class PhoneContacts
{
public:
  PhoneContacts() : _contacts() { }
 
  bool AddContact(const PhoneContact & contact)
  {
    bool  rc = false;
    string  fullName(contact.FirstName() + " " + contact.LastName());
    auto  it = _contacts.find(fullName);
    if (it == _contacts.end()) {
      _contacts[fullName] = contact;
      rc = true;
    }
    return rc;
  }
  
  bool MatchesByEitherName(const string & name,
                           vector<PhoneContact> & matches) const
  {
    if (! matches.empty()) {
      matches.clear();
    }
    for (auto i : _contacts) {
      if ((i.second.FirstName() == name)
          || (i.second.LastName() == name)) {
        matches.push_back(i.second);
      }
    }
    return (! matches.empty());
  }
 
  bool MatchByFullName(const string & firstName, const string & lastName,
                       PhoneContact & match)
  {
    bool  rc = false;
    for (auto i : _contacts) {
      if ((i.second.FirstName() == firstName)
          && (i.second.LastName() == lastName)) {
        match = i.second;
        rc = true;
        break;
      }
    }
    return rc;
  }
 
  const map<string,PhoneContact> & Contacts() const  { return _contacts; }
  map<string,PhoneContact> & Contacts() { return _contacts; }
    
  istream & Read(istream & is) { return Dwm::StreamIO::Read(is, _contacts); }
  ostream & Write(ostream & os) const { return Dwm::StreamIO::Write(os, _contacts); }
  ssize_t Read(int fd)             { return Dwm::DescriptorIO::Read(fd, _contacts); }
  ssize_t Write(int fd) const      { return Dwm::DescriptorIO::Write(fd, _contacts); }
  size_t Read(FILE *f)             { return Dwm::FileIO::Read(f, _contacts); }
  size_t Write(FILE *f) const      { return Dwm::FileIO::Write(f, _contacts); }
 
private:
  map<string,PhoneContact>  _contacts;
};
 

The astute observer will notice that the PhoneContact class is just a wrapper around a std::tuple, to avoid having to use std::get<>() directly from application code outside of this class. If you're willing to deal directly with std::get<>(), you can just do this:

typedef std::tuple<std::string,std::string,std::pair<std::string,std::string> > >  PhoneContact; 

typedef std::map<std::string,PhoneContact>  PhoneContacts; 

UnitAssert - A trivial unit testing framework

In DwmUnitAssert.hh you will find the UnitAssert() macro and a handful of support classes for unit testing. This trivial framework makes simple unit testing easy to accomplish for all exposed interfaces. This framework is used for all of the unit tests in the tests subdirectory of the libDwm source distribution, and you can look there for many examples. But its basic usage is trivial and typically boils down to just three calls: the UnitAssert() macro to assert conditions that must be true (just like assert() from the standard C library), and a call to Dwm::Assertions::Print() at the end of your test program that is typically wrapped in test of the return of Dwm::Assertions::Total().Failed().

Below is the entire contents of TestGroup.cc from the tests directory of the libDwm source distribution. You will see calls to UnitAssert() on lines 16, 21, 26, 27 and 28. On line 30, we check if there were any failed tests via Dwm::Assertions::Total().Failed(). If there were, we print them with Dwm::Assertions::Print(). If there were no failed tests, we print the total number of tests (which all passed).

extern "C" {
  #include <unistd.h>
}
 
#include "DwmGroup.hh"
#include "DwmPassword.hh"
#include "DwmUnitAssert.hh"
 
//----------------------------------------------------------------------------
//----------------------------------------------------------------------------
int main(int argc, char *argv[])
{
  gid_t  mygid = getegid();
  Dwm::Group  mygroup(mygid);
  UnitAssert(mygid == mygroup.Id());
 
  Dwm::Password  mypasswd(geteuid());
  auto  gmit = std::find(mygroup.Members().begin(), mygroup.Members().end(),
                         mypasswd.UserName());
  UnitAssert(gmit != mygroup.Members().end());
 
  struct group  *grp = getgrgid(mygid);
  Dwm::Group     setGroup(getgid());
  setGroup.Set(*grp);
  UnitAssert(setGroup.Id() == grp->gr_gid);
  UnitAssert(setGroup.Name() == grp->gr_name);
  UnitAssert(setGroup.Password() == grp->gr_passwd);
  
  if (Dwm::Assertions::Total().Failed() > 0) {
    Dwm::Assertions::Print(std::cerr, true);
    exit(1);
  }
  else {
    std::cout << Dwm::Assertions::Total() << " passed" << std::endl;
  }
  exit(0);
}

Dwm::SysLogger - decorated syslogging

The intent of Dwm::SysLogger and the Syslog() macro is to allow the automatic addition of filename, line number and syslog priority to syslog messages. No one in their right mind wants to have to add "(%s:%d)", __FILE__, __LINE__ to every syslog call in their source code. It's inane work and prone to mistakes. Syslog() can do this for you if you enable it with Dwm::SysLogger::ShowFileLocation(bool). It can also put three-character tags on each log message if you enable it with Dwm::SysLogger::ShowPriorities(bool). You can also change the minimum priority of messages to be logged via Dwm::SysLogger::MinimumPriority(int) or Dwm::SysLogger::MinimumPriority(const std::string &). This is handy when you want to toggle debug logging while a program is running, perhaps via a signal.