folly::hazptr_obj

Synopsis

Declared in <folly/synchronization/HazptrObj.h>

template<template<
    typename,
    typename,
    typename> typename Atom = atomic>
class hazptr_obj;

Private base class for objects protectable by hazard pointers.

Data members:

next_: link to next object in private singly linked lists.
reclaim_: reclamation function for this object.
cohort_tag_: A pointer to a cohort (where the object is to be pushed when retired). It can also be used as a tag (see below).

Cohorts, Tags, Tagged Objects, and Untagged Objects:

Cohorts: Cohorts (instances of hazptr_obj_cohort) are sets of retired hazptr_obj-s. Cohorts are used to keep related objects together instead of being spread across thread local structures and/or mixed with unrelated objects.

Tags: A tag is a unique identifier used for fast identification of related objects for synchronous reclamation. Tags are implemented as addresses of cohorts, with the lowest bit set (to save the space of separate cohort and tag data members and to differentiate from cohorts of untagged objects.

Tagged objects: Objects are tagged for fast identification. The primary use case is for synchronous reclamation ((e.g., the destruction of all Key and Value objects that were part of a Folly ConcurrentHashMap instance). Member function set_cohort_tag makes an object tagged.

Untagged objects: Objects that do not need to be identified separately from unrelated objects are not tagged (to keep tagged objects uncluttered). Untagged objects may or may not be associated with cohorts. An example of untagged objects associated with cohorts are Segment-s of Folly UnboundedQueue. Although such objects do not need synchronous reclamation, keeping them in cohorts helps avoid cases of a few missing objects delaying the reclamation of large numbers of link-counted objects. Objects are untagged either by default or after calling set_cohort_no_tag.

Thread Safety: Member functions set_cohort_tag and set_cohort_no_tag are not thread-safe. Thread safety must be ensured by the calling thread.

Name	Description
`hazptr_obj` [constructor]	Constructors
`operator=`	Assignment operators
`cohort`	Returns the cohort the object is associated with, if any.
`cohort_tag`	Returns the raw cohort tag, including the tag bit.
`set_cohort_no_tag`	Sets the cohort and makes the object untagged.
`set_cohort_tag`	Sets the cohort and makes the object tagged.
`tagged`	Reports whether the object is tagged.

Name	Description
`hazptr_obj_base`	hazptr_obj_base
`hazptr_obj_linked`	hazptr_obj_linked