Object Registry

Object Registry Overview

The ObjectRegistry is a means by which alternative implementations of classes can be added and used by RocksDB programs. For example, an application may provide a custom Comparator class. By registering a factory for this class with the ObjectRegistry, an instance of a class can be created.

An ObjectRegistry can be obtained via ObjectRegistry::Default or ObjectRegistry::NewInstance. An instance of a ConfigOptions has an ObjectRegistry.

The Object Library

The ObjectRegistry is divided into libraries. A library provides a set of Factories that can be used to create instances of classes. Typically, libraries are divided into comparable functionality. For example, a "Test" library may register classes used for testing, whereas factories for certain features or plugins ("Cassandra", "HDFS") may be registered in their own libraries. Classes provided as part of the core RocksDB are typically registered in the Default library.

Factories may be registered with an library individually or via a Registrar function. A Registrar function typically registers factories individually. The code below shows a registrar function and the factories being registered:

static int RegisterTestObjects(ObjectLibrary& library,
                               const std::string& /*arg*/) {
  size_t num_types;
  library.Register<TableFactory>(
      "MockTable",
      [](const std::string& /*uri*/, std::unique_ptr<TableFactory>* guard,
         std::string* /* errmsg */) {
        guard->reset(new mock::MockTableFactory());
        return guard->get();
      });
  return static_cast<int>(library.GetFactoryCount(&num_types));
}
config_options_.registry->AddLibrary("custom-tests", RegisterTestObjects, "");

This code snippet adds the "custom-tests" library to the registry. The RegisterTestFunctions registers a factory to create a MockTable.

Factories are registered using a regular expression. For example, the registered factory:

    lib->Register<EncryptionProvider>(
        "CTR(://test)?",
        [](const std::string& uri, std::unique_ptr<EncryptionProvider>* guard,
           std::string* /*errmsg*/) {
            ...
        });

Will match CTR://test or CTR. The "uri" argument to the factory will be the name that invoked this factory (e.g "CTR://test").

On success, a factory returns a pointer to the object. If the object is not static -- and can be deleted -- the guard should contain the same pointer. On error, errmsg should contain a message explaining the error.