libDwm-0.6.11
Dwm Class Library

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 re-use easy.

There are a few classes herein that I've used on nearly every software project in the last 15 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 Dwm::IO class along with the Dwm::Readable and Dwm::Writable interfaces.

Since much of the software I've written in the last 15 years has been multithreaded, I have also made heavy use of the older classes in the Dwm::Pthread namespace. Today I've replaced most of their use with std::mutex, std::thread and friends, and use instances 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 300,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 two platforms: FreeBSD and OS X. FreeBSD is my operating system of choice for servers and OS X is my operating system of choice for desktops and laptops. I occasionally update the library for Linux, but I don't currently run a Linux machine at home except for a Ubuntu VM which I use to run the unit tests.

A small sample of what's in libDwm

Dwm::IO - Serialization

Dwm::IO, 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. Dwm::IO provides serialization to/from iostream, FILEs and descriptors. Dwm::GZIO provides gzip compressed serialization. Dwm::BZ2IO provides bzip2 compressed serialization.

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 for Dwm::IO are Dwm::Readable and Dwm::Writable. The required interfaces for Dwm::GZIO are Dwm::GZReadable and Dwm::GZWritable. The required interfaces for Dwm::BZ2IO are Dwm::BZ2Readable and Dwm::BZ2Writable.

Today, the C++ programmer has several options for serialization, and the possibility of reflection in a future version of the standard. However, I wrote most of this functionality in 2004 when we didn't have a lot of options to support serialization and finalized most of it in 2007 with the addition of cleaner code for std::tuple. I couldn't do this effectively until the compilers were up to speed.

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

1 #include <fstream>
2 #include <map>
3 #include <string>
4 
5 #include "DwmIpv4Address.hh"
6 #include "DwmIO.hh"
7 
8 int main(int argc, char *argv[])
9 {
10  std::map<Dwm::Ipv4Address, std::string> hosts;
11 
12  // Read hosts from an ifstream
13  std::ifstream is("/tmp/hosts");
14 
15  if (is) {
16  Dwm::IO::Read(is, hosts);
17  is.close();
18  }
19 
20  // Do something with hosts, then...
21 
22  // Save hosts to an ofstream
23  std::ofstream os("/tmp/hosts");
24  if (os) {
25  Dwm::IO::Write(os, hosts);
26  os.close();
27  }
28 
29  return 0;
30 }
31 
32 
static std::ostream & Write(std::ostream &os, char c)
Writes c to os. Returns os.
static std::istream & Read(std::istream &is, char &c)
Reads c from is. Returns is.
Dwm::IO class definition.
Dwm::Ipv4Address class definition.

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 by Dwm::IO. Containers of containers of supported types, for example:

1 #include <fstream>
2 #include <map>
3 #include <set>
4 #include <string>
5 #include <vector>
6 
7 #include "DwmIO.hh"
8 
9 using namespace std;
10 
11 int main(int argc, char *argv[])
12 {
13  if (argc > 2) {
14  vector<map<string,set<string>>> data;
15 
16  // Read data from an ifstream
17  ifstream is(argv[1]);
18  if (is) {
19  Dwm::IO::Read(is, data);
20  is.close();
21  }
22 
23  // Do something with the data...
24 
25  // Then save to an ofstream
26  ofstream os(argv[2]);
27  if (os) {
28  Dwm::IO::Write(os, data);
29  os.close();
30  }
31  }
32 
33  return 0;
34 }
STL namespace.
static std::ostream & Write(std::ostream &os, char c)
Writes c to os. Returns os.
static std::istream & Read(std::istream &is, char &c)
Reads c from is. Returns is.
Dwm::IO class definition.

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 by Dwm::IO are lines 43 to 49 and 111 to 117. These are easy to implement, since they each require only a single call to a member of Dwm::IO. Note that I never put  using namespace std in header files. It's here just to reduce clutter on your screen.

1 #include "DwmIO.hh"
2 
3 using namespace std;
4 
5 //----------------------------------------------------------------------------
6 //----------------------------------------------------------------------------
7 class PhoneContact
8  : public Dwm::Readable, public Dwm::Writable
9 {
10 public:
11  PhoneContact() : _data() { }
12 
13  const string & FirstName() const { return get<0>(_data); }
14  const string & FirstName(const string & firstName)
15  {
16  get<0>(_data) = firstName;
17  return get<0>(_data);
18  }
19 
20  const string & LastName() const { return get<1>(_data); }
21  const string & LastName(const string & lastName)
22  {
23  get<1>(_data) = lastName;
24  return get<1>(_data);
25  }
26 
27  const set<pair<string,string> > & PhoneNumbers() const
28  { return get<2>(_data); }
29  bool AddPhoneNumber(const string & phoneName,
30  const string & phoneNumber)
31  {
32  pair<string,string> phone(phoneName, phoneNumber);
33  return get<2>(_data).insert(phone).second;
34  }
35 
36  bool RemovePhoneNumber(const string & phoneName,
37  const string & phoneNumber)
38  {
39  pair<string,string> phone(phoneName, phoneNumber);
40  return (get<2>(_data).erase(phone) == 1);
41  }
42 
43  istream & Read(istream & is) { return Dwm::IO::Read(is, _data); }
44  ostream & Write(ostream & os) const { return Dwm::IO::Write(os, _data); }
45  ssize_t Read(int fd) { return Dwm::IO::Read(fd, _data); }
46  ssize_t Write(int fd) const { return Dwm::IO::Write(fd, _data); }
47  size_t Read(FILE *f) { return Dwm::IO::Read(f, _data); }
48  size_t Write(FILE *f) const { return Dwm::IO::Write(f, _data); }
49  uint32_t StreamedLength() const { return Dwm::IO::StreamedLength(_data); }
50 
51 private:
52  tuple<string, // first name
53  string, // last name
54  set<pair<string,string> > // phone numbers
55  > _data;
56 };
57 
58 //----------------------------------------------------------------------------
59 //----------------------------------------------------------------------------
60 class PhoneContacts
61  : public Dwm::Readable, public Dwm::Writable
62 {
63 public:
64  PhoneContacts() : _contacts() { }
65 
66  bool AddContact(const PhoneContact & contact)
67  {
68  bool rc = false;
69  string fullName(contact.FirstName() + " " + contact.LastName());
70  auto it = _contacts.find(fullName);
71  if (it == _contacts.end()) {
72  _contacts[fullName] = contact;
73  rc = true;
74  }
75  return rc;
76  }
77 
78  bool MatchesByEitherName(const string & name,
79  vector<PhoneContact> & matches) const
80  {
81  if (! matches.empty()) {
82  matches.clear();
83  }
84  for (auto i : _contacts) {
85  if ((i.second.FirstName() == name)
86  || (i.second.LastName() == name)) {
87  matches.push_back(i.second);
88  }
89  }
90  return (! matches.empty());
91  }
92 
93  bool MatchByFullName(const string & firstName, const string & lastName,
94  PhoneContact & match)
95  {
96  bool rc = false;
97  for (auto i : _contacts) {
98  if ((i.second.FirstName() == firstName)
99  && (i.second.LastName() == lastName)) {
100  match = i.second;
101  rc = true;
102  break;
103  }
104  }
105  return rc;
106  }
107 
108  const map<string,PhoneContact> & Contacts() const { return _contacts; }
109  map<string,PhoneContact> & Contacts() { return _contacts; }
110 
111  istream & Read(istream & is) { return Dwm::IO::Read(is, _contacts); }
112  ostream & Write(ostream & os) const { return Dwm::IO::Write(os, _contacts); }
113  ssize_t Read(int fd) { return Dwm::IO::Read(fd, _contacts); }
114  ssize_t Write(int fd) const { return Dwm::IO::Write(fd, _contacts); }
115  size_t Read(FILE *f) { return Dwm::IO::Read(f, _contacts); }
116  size_t Write(FILE *f) const { return Dwm::IO::Write(f, _contacts); }
117  uint32_t StreamedLength() const { return Dwm::IO::StreamedLength(_contacts); }
118 
119 private:
120  map<string,PhoneContact> _contacts;
121 };
122 
STL namespace.
static std::ostream & Write(std::ostream &os, char c)
Writes c to os. Returns os.
static std::istream & Read(std::istream &is, char &c)
Reads c from is. Returns is.
Dwm::IO class definition.
This class defines an interface for classes that can write their contents to an ostream, file descriptor or FILE pointer.
Definition: DwmWritable.hh:58
static uint32_t StreamedLength(char c)
Returns the number of bytes that would be written if we called Write() for a char.
Definition: DwmIO.hh:92
This class defines an interface for classes that can read their contents from an istream, file descriptor or FILE pointer.
Definition: DwmReadable.hh:58

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 pring the total number of tests (which all passed).

1 extern "C" {
2  #include <unistd.h>
3 }
4 
5 #include "DwmGroup.hh"
6 #include "DwmPassword.hh"
7 #include "DwmUnitAssert.hh"
8 
9 //----------------------------------------------------------------------------
11 //----------------------------------------------------------------------------
12 int main(int argc, char *argv[])
13 {
14  gid_t mygid = getegid();
15  Dwm::Group mygroup(mygid);
16  UnitAssert(mygid == mygroup.Id());
17 
18  Dwm::Password mypasswd(geteuid());
19  auto gmit = std::find(mygroup.Members().begin(), mygroup.Members().end(),
20  mypasswd.UserName());
21  UnitAssert(gmit != mygroup.Members().end());
22 
23  struct group *grp = getgrgid(mygid);
24  Dwm::Group setGroup(getgid());
25  setGroup.Set(*grp);
26  UnitAssert(setGroup.Id() == grp->gr_gid);
27  UnitAssert(setGroup.Name() == grp->gr_name);
28  UnitAssert(setGroup.Password() == grp->gr_passwd);
29 
30  if (Dwm::Assertions::Total().Failed() > 0) {
31  Dwm::Assertions::Print(std::cerr, true);
32  exit(1);
33  }
34  else {
35  std::cout << Dwm::Assertions::Total() << " passed" << std::endl;
36  }
37  exit(0);
38 }
#define UnitAssert(e)
This macro is used just like assert(), but populates Assertions so we can report results at the end o...
Definition: DwmUnitAssert.hh:277
Encapsulates an /etc/group entry.
Definition: DwmGroup.hh:61
Encapsulates an /etc/passwd entry.
Definition: DwmPassword.hh:61
static std::ostream & Print(std::ostream &os, bool onlyFailed=false)
Prints to an ostream.
Dwm::Assertions class definition and UnitAssert() macro for unit tests.
static AssertionCounter Total()
Returns the total passed and failed counter.
uint64_t Failed() const
Returns the failed counter.
Dwm::Password class definition.
Dwm::Group class definition.

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.

Dwm::Pacer - pacing repetitive calls

Documentation forthcoming

Networking classes

Documentation forthcoming for Dwm::HostPinger, ICMP classes, TCP classes, Dwm::Pcap, etc.

Dwm::Pcap - simple pcap wrapper class

Dwm::Pcap is a simple wrapper class for pcap (packet capture library). It doesn't do anything beyond what libpcap provides, it simply wraps in in a C++ interface.

Dwm::HostPinger - pinging IP hosts

Dwm::HostPinger is a class that allows the 'pinging' of one or more IP hosts using ICMP or TCP. The overall packet rate may be controlled, and an object may be registered for the reception of responding host, receive time and round-trip time.

ICMP classes

Dwm::ThreadQueue - inter-thread communication

Documentation forthcoming.