#include "tensorstore/context.h"
class tensorstore::Context;

Immutable collection of lazily-constructed “resources”.

This is used as a holder for, among other things, shared thread pools, cache pools, and authentication credentials used by various components in TensorStore.

A resource is an arbitrary C++ object that may be accessed using a Context::Resource handle, which provides a const, reference counted view of the object. Note that while the object itself is const, it may refer to mutable state, such as a cache. Resources are constructed lazily within the Context object from an unresolved Resource spec (which is created from a JSON representation) when first accessed.

Context resources are used with the TensorStore library to specify TensorStore driver and kvstore driver configuration options that do not affect the identity of the KvStore or TensorStore; in general, the contents of a KvStore or TensorStore should be identical for any valid context. For example, a file or bucket path for accessing data should not be specified as a context resource, while authentication credentials, caching, and concurrency options should be specified as context resources.

Example usage:

auto spec_result = Context::Spec::FromJson({
  {"data_copy_concurrency", {{"limit", 4}}},
  {"data_copy_concurrency#a", {{"limit", 8}}},
});
if (!spec_result) {
  // Handle error
}
auto resource_spec_result =
    Context::Resource<internal::DataCopyConcurrencyResource>
    ::FromJson("data_copy_concurrency");
if (!resource_spec_result) {
  // Handle error
}
auto context = Context(*spec_result);
auto resource_result = context.GetResource(
    resource_spec_result->value());
if (!resource_result) {
  // Handle error
}
// Can access executor member of context resource.
(*resource_result)->executor([] {
  // task body
});
// Access other executor.
auto resource2 = context.GetResource(
    Context::Resource<internal::DataCopyConcurrencyResource>
    ::FromJson("data_copy_concurrency#a").value()).value();
resource2->executor([] { /* task body */ });

Context::Spec and unresolved Context::Resource instances serve as intermediate representations between JSON and the actual context and context resource, respectively. This indirection makes it possible to validate a context or resource specification without actually constructing the resource; this is especially useful if one process/machine prepares a specification for use by another process/machine. It also makes it possible to properly handle shared resources when serializing back to JSON.

The Context::Resource type is actually a variant type that can hold either a context resource or a context resource spec. Context::Resource<Provider>::FromJson returns an unresolved context resource spec, which specifies any parameters of the context resource (e.g. memory limits for a cache pool) but does not represent a specific resource (e.g. the actual cache pool). Binding the context resource spec with a Context converts the context resource spec to an actual context resource. Unbinding a context resource converts it back to a context resource spec. These binding and unbinding operations can also be applied to data structures like tensorstore::Spec and tensorstore::kvstore::Spec that indirectly hold context resources.

Types

using ToJsonOptions = JsonSerializationOptions;
using FromJsonOptions = JsonSerializationOptions;

JSON serialization options.

class Spec;

Parsed specification of a collection of context resources.

class Resource<Provider>;

Variant type that either specifies an unresolved context resource, or holds a shared handle to a context resource.

Constructors

Context();

Constructs a null context.

explicit Context(const Spec& spec, Context parent = {});

Constructs a context from a Spec.

Methods

static Context Default();

Constructs a new default context.

static Result<Context> FromJson(::nlohmann::json json_spec,
                                Context parent = {},
                                FromJsonOptions options = {});

Constructs a context from a JSON spec.

Result<Resource<Provider>>
GetResource(const Resource<Provider>& resource_spec) const;
Result<Resource<Provider>>
GetResource(const ::nlohmann::json& json_spec) const;
Result<Resource<Provider>> GetResource() const;

Returns a resource or the default resource for a given provider.

Context::Spec spec() const;

Returns the Spec used to create this context.

Context parent() const;

Returns the parent Context, if any.

Conversion operators

explicit operator bool() const;

Returns true if this is not a null context.

Friend functions

friend bool operator==(const Context& a, const Context& b);
friend bool operator!=(const Context& a, const Context& b);

Returns true if the two context objects refer to the same underlying shared state.

enum class tensorstore::ContextBindingMode;

Specifies how context bindings should be handled for Spec-like types, such as tensorstore::kvstore::Spec and tensorstore::Spec.

enum class tensorstore::ContextBindingState;

Indicates the binding state of context resources within a Spec-like type, such as tensorstore::Spec and tensorstore::kvstore::Spec.