5. C++ Library

5.1. Overview

The C++ library for WebMapReduce attempts to efficiently emulate map-reduce behavior as provided by Hadoop. It is composed of two namespaces, and makes heavy use of std::string. Much of the library is not intended to be exposed to users, and is reserved for background use in ensuring correct behavior. The key parts of the library that users should be familiar with are the public elements of wmr_common.h and datastream.h.

This library is designed such that users are only required to provied two pieces of code: the mapper class and the reducer class. These classes must fit the following template:

class mapper
  void map(std::string key, std::string value);
class reducer
  void reduce(std::string key, wmr::datastream values);

The classes may also have constructors and destructors, but the constructer cannot take arguments. Once these classes are provided, the library instantiates them, and calls the methods map() and reduce(). Users should note that they must explicitly include the wmr namespace (or fully qualify library types) to use library classes.

5.1.1. Namespace/Class View

  • namespace wmr
    • class datastream
    • class utility
    • namespace internal
      • class wmr_common
      • class key_value_stream

The wmr namespace is intended to be exposed to users, while the internal namespace is meant to be used behind the scenes. Technically, users may access the internal namespace, but doing so may cause unexpected results.

5.2. API

5.2.1. Class datastream

File: datastream.h

class datastream
  datastream(const datastream &);

  bool eof(void) const;
  const std::string & associated_key(void) const;

  template <typename T>
  datastream & operator>>(T &);

  template <typename T>
  datastream & get(T &);

  datastream & operator>>(std::stringstream &);
  datastream & get(std::stringstream &);

  // ...

The datastream class is a one-way stream used to retrieve values in the reducer. Rather than load the entire list of values into memory at the same time, the datastream class works in conjunction with wmr::internal::key_value_stream to defer loading until a value is needed. Since values are fed through standard input to the program running as the reducer, there is no way to know in advance how many values a particular key has. Therefore, by associating a datastream with a key, it is possible to check for the end of the list by receiving a key-value pair that does not have the same key. Due to the shuffling stage of map-reduce guaranteed by Hadoop, it is known that all key-value pairs will arrive to the reducer in-order, which guarantees the behavior of datastream.


datastream objects are provided by the reducer and should not be created by hand.

datastream& datastream::operator>><T>(T&)

Calls datastream & datastream::get<T>(T &)().

datastream& datastream::operator>>(std::stringstream&)

Calls datastream & datastream::get(std::stringstream &)()

datastream& datastream::get<T>(T&)

Sets the first argument to be the current value, then advances the stream (gets the next value in the stream).

datastream& datastream::get(std::stringstream&)

Adds the current value to the first argument, then advances the stream (gets the next value in the stream).

5.2.2. Class utility

File: wmr_common.h

class utility
  template <typename T>
  static std::string toString(const T &);

  template <typename T>
  static T fromString(const std::string &);

  // Alternatives to fromString<T>() without template arguments
  static int stringToInt(const std::string &);
  static long stringToLong(const std::string &);
  static float stringToFloat(const std::string &);
  static double stringToDouble(const std::string &);
  static bool stringToBool(const std::string &);

  static std::vector<std::string> split(const std::string &, char);
  static std::vector<std::string> split_multi(const std::string &, const std::string &);

template <typename T, typename K>
static void emit(const T &, const K &);

Provides a set of helper methods to those using this library. In particular it focuses on string manipulation and conversion since data is passed to and from the mapper and reducer as strings.

static std::string utility::toString(const T&)

Converts data of type T to a std::string by using a std::stringstream object. Returns the string that is created.

static T utility::fromString(const std::string&)

Converts the given std::string to type T by using a std::stringstream object. Returns the data that is created from the string.

static std::vector<std::string> utility::split(const std::string&, char)

Splits the given string (argument 1) on every instance of the given delimiter (argument 2). Only a single delimiter may be passed to this method. Returns a std::vector of std::string objects resulting from the split.

static std::vector<std::string> utility::split_multi(const std::string&, const std::string&)

Splits the given string (argument 1) on every instance of any of the delimiters passed in argument 2. If two delimiters occur side-by-side, they are skipped (no empty string is provided). Returns a :class:std::vector of std::string objects resulting from the split.

static void emit(const T&, const K&)

Prints the first argument followed by the delimiter specified by wmr_common (almost always tab) followed by the second argument to standard output. Emit can only be called with types that support the << operator with a std::ostream object (cout).

Convenience methods to avoid templates:

static int utility::stringToInt(const std::string&)

Since the generic utility::fromString method returns data of type T, the template parameters must be given when calling it. Given the audience of WMR and the strong emphasis on beginning CS students, non-templated methods have been provided in case providing template arguments provides to be too confusing.

This method calls utility::fromString with the appropriate template parameter.

static long utility::stringToLong(const std::string&)

See utility::stringToInt().

static float utility::stringToFloat(const std::string&)

See utility::stringToInt().

static double utility::stringToDouble(const std::string&)

See utility::stringToInt().

static bool utility::stringToBool(const std::string&)

See utility::stringToInt().

5.3. Example Usage

This section presents the code to run a word count job using WebMapReduce and the C++ library.

5.3.1. Example Mapper

#include <string>
#include <vector>

class mapper
  void map(std::string key, std::string value)
    using std::string;
    using std::vector;

    // split the line into a vector of words
    vector<string> words = wmr::utility::split(key, ' ');
    // loop through the vector, and emit each word with a 1
    for (size_t i = 0; i < words.size(); ++i)
      wmr::emit(words.at(i), 1);

5.3.2. Example Reducer

#include <string>

class reducer
  void reduce(std::string key, wmr::datastream stm)
    using std::string;

    long sum = 0;
    string value;

    // grab data from the stream until there are no more values
    while (!stm.eof())
      stm >> value;
      // convert the value to a number, then add it to the
      // running total
      sum += wmr::utility::fromString<long>(value);

    // emit the key with its total count
    wmr::emit(key, sum);