
=head1 NAME

OpenTracing::Interface::ContextReference - Defines the ContextReference

=head1 SYNOPSIS

    package OpenTracing::Implementation::MyBackendService::ContextReference;
        
    sub new_child_of {
        ...
    }
    
    sub new_follows_from {
        ...
    }
    
    sub get_referenced_context {
        ...
    }
    
    sub type_is_child_of {
        ...
    }
    
    sub type_is_follows_from {
        ...
    }
    
    BEGIN {
        use Role::Tiny::With;
        with 'OpenTracing::Interface::ContextReference'
            if $ENV{OPENTRACING_INTERFACE};
    } # check at compile time, perl -c will work
    
    1;

=head1 DESCRIPTION

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

References are used by C<Tracer> methods C<start_span> and C<start_active_span>
to create "casual span references"

See L<OpenTracing References|http://opentracing.io/spec/#causal-span-references>



=head1 CONSTRUCTOR METHODS



=head2 C<new_child_of>

Creates a C<SpanContext> C<ContextReference> for which L<type_is_child_of> is
'true'.

    ContextReference->new_child_of( $span_context );

=over

=item Required Positional Parameter(s)

=over

=item span_context, a B<required> C<SpanContext>

The sapn context that the returned context reference should should refer to.

=back

=item Returns

=over

=item C<ContextReference>

The newly instantiated reference.

=back

=back



=head2 C<new_follows_from>

Creates a C<SpanContext> C<ContextReference> for which L<type_is_follows_from>
is 'true'.

    ContextReference->new_follows_from( $span_context );

=over

=item Required Positional Parameter

=over

=item span_context, a B<required> C<SpanContext>

The context the returned context reference should should refer to.

=back

=item Returns

=over

=item C<ContextReference>

A newly instantiated context reference

=back

=back



=head1 INSTANCE METHODS



=head2 C<get_referenced_context>

Returns the original referenced C<SpanContext>.

    $span_context = $reference->get_referenced_context;

=over

=item Parameter(s)

=over

I<none>

=back

=item Returns

=over

=item C<SpanContext>

The span context being referenced.

=back

=back



=head2 C<type_is_child_of>

Returns 'true' iff the C<ContextReference> is a C<CHILD_OF> type is, most
likely, instantiated with the C<new_child_of> constructor.

    say "I'm a CHILD_OF context reference"
        if $context_reference->type_is_child_of;

=over

=item Parameter(s)

=over

I<none>

=back

=item Returns

=over

=item C<Bool>

=back

=back



=head2 Ctype_is_follows_from>

Returns 'true' iff the C<ContextReference> is a C<FOLLOWS_FROM> type is, most
likely, instantiated with the C<new_follows_from> constructor.

    say "I'm a FOLLOWS_FROM context reference"
        if $context_reference->type_is_child_of;

=over

=item Parameter(s)

=over

I<none>

=back

=item Returns

=over

=item C<Bool>

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

