
=head1 NAME

OpenTracing::Interface::ScopeManager - A role that defines the ScopeManager

=head1 SYNOPSIS

    package OpenTracing::Implementation::MyBackendService::ScopeManager;
        
    sub activate_span {
        ...
    }
    
    sub get_active_scope {
        ...
    }
    
    BEGIN {
        use Role::Tiny::With;
        with 'OpenTracing::Interface::ScopeManager'
            if $ENV{OPENTRACING_INTERFACE};
    } # check at compile time, perl -c will work
    
    1;

=head1 DESCRIPTION

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

The C<ScopeManager> interface abstracts both the activation of C<Span> instances
via L<activate_Span> and access to an active C<Scope> via L<get_active_scope>.



=head1 INSTANCE METHODS



=head2 C<activate_span>

Set the specified C<Span> as the active instance for the current context
(usually a thread).

    my $span = $tracer->start_span( 'some operation'
        ignore_active_span => 1
    );
    
    my $scope_manager = $tracer->get_scope_manager;
    
    my $scope = $scope_manager->activate_span( $span,
        finish_span_on_close => 0
    );

The returned C<Scope> represents the active state for the span. Once its active
period is due, C<< $scope->close() >> ought to be called.
Observe the span will be automatically finished when C<< $scope->close() >> is
called.

=over

=item Required Positional Parameter(s)

=over

=item span, a B<required> C<Span> object.

The span to be activated.

=back

=item Named Options

=over

=item C<finish_span_on_close>, as a C<Bool>

When set to false, the span will not be automatically finished when the scope
is being closed. This is 'true' by default.

=back

=item Returns

=over

=item C<Scope>

The scope object for the given span.

=back

=back



=head2 Cget_active_scope>

Return the currently active C<Scope> which can be used to access the
currently active C<Span>, using C<< $scope->get_span >>.

    my $manager = $tracer->get_scope_manager;
    
    my $scope = $manager->get_activate_scope;

=over

=item Positional Parameter(s)

=over

I<none>

=back

=item Returns

=over

=item Maybe C<Scope>

The currently active scope or C<undef> if none.

=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

=cut



=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.
