class CordzInfo

TrackCord creates a CordzInfo instance which tracks important metrics of

a sampled cord, and stores the created CordzInfo instance into `cord'. All

CordzInfo instances are placed in a global list which is used to discover

and snapshot all actively tracked cords. Callers are responsible for

calling UntrackCord() before the tracked Cord instance is deleted, or to

stop tracking the sampled Cord. Callers are also responsible for guarding

changes to the 'tree' value of a Cord (InlineData.tree) through the Lock()

and Unlock() calls. Any change resulting in a new tree value for the cord

requires a call to SetCordRep() before the old tree has been unreffed

and/or deleted. `method` identifies the Cord public API method initiating

the cord to be sampled.

Requires `cord` to hold a tree, and `cord.cordz_info()` to be null.

Identical to TrackCord(), except that this function fills the

`parent_stack` and `parent_method` properties of the returned CordzInfo

instance from the provided `src` instance if `src` is sampled.

This function should be used for sampling 'copy constructed' and 'copy

assigned' cords. This function allows 'cord` to be already sampled, in

which case the CordzInfo will be newly created from `src`.

Maybe sample the cord identified by 'cord' for method 'method'.

Uses `cordz_should_profile` to randomly pick cords to be sampled, and if

so, invokes `TrackCord` to start sampling `cord`.

Maybe sample the cord identified by 'cord' for method 'method'.

`src` identifies a 'parent' cord which is assigned to `cord`, typically the

input cord for a copy constructor, or an assign method such as `operator=`

`cord` will be sampled if (and only if) `src` is sampled.

If `cord` is currently being sampled and `src` is not being sampled, then

this function will stop sampling the cord and reset the cord's cordz_info.

Previously this function defined that `cord` will be sampled if either

`src` is sampled, or if `cord` is randomly picked for sampling. However,

this can cause issues, as there may be paths where some cord is assigned an

indirect copy of it's own value. As such a 'string of copies' would then

remain sampled (`src.is_profiled`), then assigning such a cord back to

'itself' creates a cycle where the cord will converge to 'always sampled`.

For example:

Cord x;

for (...) {

// Copy ctor --> y.is_profiled := x.is_profiled | random(...)

Cord y = x;

...

// Assign x = y --> x.is_profiled = y.is_profiled | random(...)

// ==> x.is_profiled |= random(...)

// ==> x converges to 'always profiled'

x = y;

}

Stops tracking changes for a sampled cord, and deletes the provided info.

This function must be called before the sampled cord instance is deleted,

and before the root cordrep of the sampled cord is unreffed.

This function may extend the lifetime of the cordrep in cases where the

CordInfo instance is being held by a concurrent collection thread.

Returns the current value of `rep_` for testing purposes only.

Invokes UntrackCord() on `info` if `info` is not null.

Retrieves the oldest existing CordzInfo.

Retrieves the next oldest existing CordzInfo older than 'this' instance.

Locks this instance for the update identified by `method`.

Increases the count for `method` in `update_tracker`.

Sets the current value of `rep_` for testing purposes only.

Unlocks this instance. If the contained `rep` has been set to null

indicating the Cord has been cleared or is otherwise no longer sampled,

then this method will delete this CordzInfo instance.

Asserts that this CordzInfo instance is locked.

Updates the `rep` property of this instance. This methods is invoked by

Cord logic each time the root node of a sampled Cord changes, and before

the old root reference count is deleted. This guarantees that collection

code can always safely take a reference on the tracked cord.

Requires a lock to be held through the `Lock()` method.

TODO(b/117940323): annotate with ABSL_EXCLUSIVE_LOCKS_REQUIRED once all

Cord code is in a state where this can be proven true by the compiler.

Returns the current `rep` property of this instance with a reference

added, or null if this instance represents a cord that has since been

deleted or untracked.

Returns the stack trace for where the cord was first sampled. Cords are

potentially sampled when they promote from an inlined cord to a tree or

ring representation, which is not necessarily the location where the cord

was first created. Some cords are created as inlined cords, and only as

data is added do they become a non-inlined cord. However, typically the

location represents reasonably well where the cord is 'created'.

Returns the stack trace for a sampled cord's 'parent stack trace'. This

value may be set if the cord is sampled (promoted) after being created

from, or being assigned the value of an existing (sampled) cord.

Retrieves the CordzStatistics associated with this Cord. The statistics

are only updated when a Cord goes through a mutation, such as an Append

or RemovePrefix.