SOSS C++ Native Client Developer's Guide

ScaleOut StateServer is a registered trademark of ScaleOut Software, Inc.

Microsoft, Visual Studio, and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.


Introduction

ScaleOut StateServer’s C++ Native Client API allows C++ applications to easily access objects and advanced functionality in the ScaleOut StateServer service. The API emphasizes and encourages the use of modern, familiar C++ idioms and libraries. For example, serialization can be performed by the popular Protocol Buffers library, Boost is used throughout (smart pointers, containers, date/time support, etc.), and the standard C++ library is used as much as possible (strings, exceptions, collections, etc.).

While ScaleOut Software has offered a low-level C API for native code development for years, the new C++ Native Client API offers rich, intuitive features to developers that simplify native development, including:

  • Object-oriented, collection-based semantics for accessing objects in ScaleOut StateServer, providing "named caches" of objects using abstractions that are similar to those available in ScaleOut’s Java and .NET APIs.
  • Integrated support for storage of Google Protocol Buffer objects, including automatic serialization/deserialization of messages and optional indexing of annotated fields.
  • An extensible object model that makes it easy to support custom serialization engines.
  • A fully coherent, in-process client cache that minimizes network and deserialization overhead.
  • Simplified query support with intuitive query filter expressions.
  • RAII-style wrappers around lock tickets returned by the server to help ensure that locked objects are always freed correctly.
  • Automatic memory management of retrieved objects (using boost::shared_ptr).
  • Automatic, thread-safe management of connections to the SOSS service.
  • Simplified key usage: many simple data types can be implicitly converted to 32-byte StateServer keys (including strings, which are automatically hashed using SHA-256).
  • Automatic lock retries when attempting to acquire exclusive access to an object that is locked by another client/thread.
  • One-time object creation when multiple client threads attempt to insert an object in the event of a simultaneous cache miss.
  • Default policy options that can be configured for an entire named cache of similar objects.

The C++ Native Client API was designed to be built and run on Linux systems using GCC 4.4 (circa 2009) and newer. To strike a balance that allows support for the older compilers used on some enterprise-grade distributions of Linux, some newer C++11 features were not used, and the API uses the widely-available Boost C++ libraries instead (releases of Boost going back to version 1.41, circa 2009, have been verified to work). So, for example, rather than returning a std::shared_ptr to a retrieved object, the API returns a boost::shared_ptr.

The API is also available for Windows developers: Visual Studio 2013 is currently supported.