A hierarchy of memory‐safety levels for a type, from least to most safe.

Synopsis

Declared in <folly/lang/SafeAlias‐fwd.h>

enum class safe_alias : int;

Description

ENUM ORDER IS IMPORTANT! Categories go from "least safe to most safe". Always use >= for safety gating.

Note: Only async_closure*() from folly coro/safe/ use the middle safety levels shared_cleanup, after_cleanup_ref, and co_cleanup_safe_ref. Normal user code should stick to maybe_value and unsafe.

Members

Name

Description

unsafe

Definitely has aliasing, we know nothing of the lifetime.

unsafe_closure_internal

Implementation detail of async_closure, used for creating closure_task, a restricted‐usage safe_task. Other code should treat this as unsafe. safe_task.h & Captures.h explain the rationale.

unsafe_member_internal

Implementation detail of async_closure, used for creating member_task, a restricted‐usage safe_task. Other code should treat this as unsafe. Closure‐related code that distinguishes this from unsafe_closure_internal expects this value to be higher.

shared_cleanup

Used only in async_closure*() ‐‐ the minimum level it considers safe for arguments, and the minimum level of safe_task it will emit. ‐ Represents an arg that can schedule a cleanup callback on an ancestor's cleanup arg A. This safety level cannot be stronger than after_cleanup_ref because otherwise such a ref could be passed to a cleanup callback on a different ancestor's cleanup arg B ‐‐ and A could be invalid by the time B runs. ‐ Follows all the rules of after_cleanup_ref. ‐ Additionally, when a shared_cleanup ref is passed to async_closure, it knows to mark its own args as after_cleanup_ref. This prevents the closure from passing its short‐lived capture`s into a new callback on the longer‐lived `shared_cleanup arg. Conversely, in the absence of shared_cleanup args, it is safe for async_closure to upgrade after_cleanup_capture*<Ref>`s to `capture*<Ref>`s, since its cleanup will terminate before the parent's will start. Explained in detail in `Captures.md.

closure_min_arg_safety

async_closure won't take unsafe* args. It is important that we disallow unsafe_closure_internal in particular, since this is part of the Captures.h mechanism that discourages moving async_closure capture wrappers out of the closure that owns it (we can't prevent it).

after_cleanup_ref

Used only in async_closure*() when it takes a co_cleanup_capture ref from a parent: ‐ NOT safe to reference from tasks spawned on co_cleanup_capture args. ‐ Otherwise, just like co_cleanup_safe_ref.

co_cleanup_safe_ref

Used only in async_closure*(): ‐ Unlike after_cleanup_ref, is safe to reference from tasks spawned on co_cleanup_capture args ‐‐ because we know these belong to the current closure. ‐ Outlives the end of the current closure's cleanup, and is thus safe to use in after_cleanup{} or sub‐closures. ‐ Safe to pass to sub‐closures. ‐ NOT safe to return or pass to callbacks from ancestor closures.

maybe_value

Looks like a "value", i.e. alive as long as you hold it. Remember this is just a HEURISTIC ‐‐ a ref inside a struct will fool it.

Created with MrDocs