Skip to content

Document which objects are "expensive" to create. #802

Closed

Description

@coryan

"Expensive" is a relative term, but we should setup some basic metrics: some constructors just allocate a few objects, others open connections to remote servers. We should give some guidance to users about the relative costs of these operations, for example, TableAdmin could say:

/**
 * Normal documentation stuff here.
 *
 * @par Cost
 * Creating a new object of type TableAdmin is comparable to creating a few objects of type
 * std::string or a few objects of type std::shared_ptr<int>. The class represents a shallow handle
 * to a remote object.
 */
class TableAdmin ...

Whereas the documentation to AdminClient, DataClient, and InstanceClient could say:

/**
 * Normal documentation stuff here.
 *
 * @par Cost
 * Applications should avoid unnecessarily creating new objects of type AdminClient. Creating
 * a new object of this type typically requires connecting to the Cloud Bigtable servers, and
 * performing the authentication workflows with Google Cloud Platform. These operations can
 * take many milliseconds, therefore applications should try to reuse the same AdminClient
 * instances when possible.
 */
class AdminClient ...

Activity

  1. added a commit that references this issue on Sep 28, 2018
    00aebad
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

api: bigtableIssues related to the Bigtable API.

Type

No type

Projects

No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions