
=head1 NAME

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

=head1 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;

=head1 DESCRIPTION

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

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

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



=head1 INSTANCE METHODS



=head2 C<close>

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

    $scope->close;

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

=over

=item Parameter(s)

=over

I<none>

=back

=item Returns

=over

=item C<Invocant>

The C<Scope> instance <$self>, for ease of chaining (although the usefulness is
doubtfull).

=back

=back



=head2 C<get_span>

Returns the C<Span> that's been scoped by this C<Scope>

    my $span = $scope->get_span

=over

=item Parameter(s)

=over

I<none>

=back

=item Returns

=over

=item C<Span>

The span that's been scoped by this scope.

=back

=back



=head1 SEE ALSO

=over

=item L<OpenTracing::Interface>

Describes the API definition for OpenTransport implementations written in the
Perl5 language.

=item L<OpenTracing::Types>

A library of L<Type::Tiny> type constraints that provides Duck Type checks for
all common elements that conform L<OpenTracing::Interface>

=back



=head1 CAVEATS

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.



=head1 AUTHOR

Theo van Hoesel <tvanhoesel@perceptyx.com>



=head1 COPYRIGHT AND LICENSE

'OpenTracing API for Perl' is Copyright (C) 2019 .. 2020, Perceptyx Inc

This library is free software; you can redistribute it and/or modify it under
the terms of the Artistic License 2.0.

This library is distributed in the hope that it will be useful, but it is
provided "as is" and without any express or implied warranties.

For details, see the full text of the license in the file LICENSE.
