NAME

OpenTracing::Interface::Scope - A role that defines the SpanContext interface

SYNOPSIS

package OpenTracing::Implementation::MyBackendService::Scope;
    
sub close {
    ...
}

sub get_span {
    ...
}

BEGIN {
    use Role::Tiny::With;
    with 'OpenTracing::Interface::Scope'
        if $ENV{OPENTRACING_INTERFACE};
} # check at compile time, perl -c will work

1;

DESCRIPTION

This 'role' describes the interface for any OpenTracing Scope implementation.

A Scope formalizes the activation and deactivation of a Span, usually from a CPU standpoint.

Many times a Span will be extant (in that finish() has not been called) despite being in a non-runnable state from a CPU/scheduler standpoint. For instance, a Span representing the client side of an RPC will be unfinished but blocked on IO while the RPC is still outstanding. A Scope defines when a given Span is scheduled and on the path.

METHODS

close

Mark the end of the active period for the current thread and Scope, updating the ScopeManager::active() in the process.

NOTE: Calling close more than once on a single Scope instance leads to undefined behavior.

Parameters

none

Returns

nothing, <undef> or what ever is appropriate for the calling context.

get_span

Returns the Span that's been scoped by this Scope

Parameters

none

Returns

The Span that's been scoped by this Scope

CAVEATS

This description is using around method modifiers that basically wraps them around the real implementation. These method modifiers provide a 'readable' and reusable interface, describing the inputs and outputs, using type constraints.

Consumers of this role, or implementors of the interface are MUST implement each method mentioned below. Not doing so will result in compilation errors.

Since this role does nothing else than checking input and output, it is useful during development. Most likely it can be switched off safely in production environments.