---

NMSTL Documentation

0.0.1

Introduction

NMSTL is the Networks, Messaging, Servers, and Threading Library, a portable C++ library for writing, well, networking and messaging components, servers, and threaded applications. In general, the intention is that NMSTL is to "systems stuff" what STL is to algorithms and containers.

NMSTL contains lots of components intended to make it easier to write applications in C++. It's high-performance - as in STL, nearly everything is implemented such that a good compiler will inline and optimize away nearly all the object-oriented overhead.

Components

Here's what's included so far. NMSTL is still just a baby, but it'll be growing up fast over the next few weeks.

• Threading. Quite standard really - just pthreads and locking so far (just like every other threading library you've ever used). As in Java, each thread is an object whose run method is invoked in a separate thread.

  NMSTL introduces the locking construct which makes it easier to write code that automatically releases a lock at the end of a block - no more accidentally forgetting to drop your mutex (an endless source of pain in debugging concurrent apps).

  class MyClass {
      mutex m;
      int some_function()
      {
          locking (m)
          {
             if (foo == bar)
                 return 89;
             else
                 ...;
          }
          return 33;
      }
  }
  

• Threadsafe containers. Just queues right now, but it's real easy to write them so I'll be adding more.

• I/O and networking. Say goodbye to ioctl and fcntl, sockaddr_in and sockaddr_un, gethostbyxxx, socket and bind and friends. Opening a connection, is as easy as in Java (and you get to do things either synchronously or asynchronously).

• Asynchronous I/O. Register handlers for the file descriptors you're interested in and get called on read/write availability (as you wish). Or use a buffered handler which takes care of the reading and writing for you. Or use a packetized handler which takes care of reading and writing whole packets for you (with an arbitrary header which you define - gotta love templates!). Think of it as "libasync lite."

• A debugging and logging framework. To generate debugging, informative, or error messages, use one of these macros:

  DEBUG << arg1 << arg2 << ... ;
  INFO << arg1 << arg2 << ... ;
  WARN << arg1 << arg2 << ... ;
  ERROR << arg1 << arg2 << ... ;
  FATAL << arg1 << arg2 << ... ;
  

  Those args are like varargs - you can use, with type safety, anything that will convert to a string:

  inet_address addr = ...;
  INFO << "Accepted connection from " << addr <<
      " in thread " << thread::self();
  

  Using one of these macros generates a debugging message containing the file name, line number, and your arguments. The debug level can be individually configured in the environment of the calling process (e.g., your shell) for each source file, so you can turn on debugging only for particular files (XXX: not yet; currently only one debug level). Eventually this facility will be expanded to support customization of format and integrated syslogging.

• Documentation. NMSTL is documented throughout using Doxygen (XXX: not stuff I've written in the last few days yet).

---