=pod

=head1 NAME

GC - The interface to the runtime Garbage collector.

=head1 SYNOPSIS

class Philosopher is GC::timely {

  has Fork::Lock $.lfork;
  has Fork::Lock $.rfork;

  method dine {
    $.lfork.grab;
    $.rfork.grab;
    ...
  }

  method DESTORY {
    $.rfork.release;
    $.lfork.release;
  }
}


my $long_lived_configuration_verbal_that_dosnt_need_much_checking is GC::tardy;

my @pantheon of God is GC::immortal;

sub draw ($display,@frames) {
  no GC::delay;  # Slowing down to check garbage would upset our little
                 # animation.
  for @frames -> {$display.show($_)}
}

=head1 DEFINITIONS

# These are all defined in terms of "objects", the GC doesn't just
# work on objects, it should be cell or container I think.

=over

=item origin scope

The lexical scope where an object was created. 

=item current scope

The lexical scope where this thread is currently executing.

=item priority

How important is it that garbage is collected (high priority == more cpu use,
less ram use)

=item delay

Pauses in the main flow that have nothing to do with priority. No delay could
mean less performance, but more responsiveness. Applicable to event loops
and such.   

=item timelyness

The property of an object such that its 
finalization subroutine is called the moment it becomes 
unreachable. This is important for objects using finalizers for 
resource management, especially when an unreleased resource 
could cause deadlock. 

=item finalization

The act of calling an object's finalize subroutine, and the release of its
memory. 

=back



=head1 ADJECTIVES

The GC API supplies the following adjectives.

=over

=item GC::timely

Requests timely destruction, that is the object is collected as soon
as it is no longer visible.  Uses for this taint are to ensure release
of expencive resources, and to support porting of Perl5 code that
expects timely destruction.

=item GC::tardy

Indercates to the GC the object is long lived and unlikely to leave
program visibility.  GCs may use this infomation for optimization,
for example generational GCs could artificially age objects marked
as tardy.

=item GC::immortal

Prevents collection of this object even when it has passed out of
visibility.

# Is this even a good idea?  It may be usefull for FFI.  Though it's
# clearly a heavy wizardy type of thing.  If nobody thinks it may be
# useful I think this dangerous beast can be removed even before it
# sees the light of day.

=item GC::keystone

Indicates to the GC the objects that this object has references to
are only referenced by this object.  Hence if this object is no longer
visible then all of the objects that this object refers to are also no
longer visible.

GCs may use this infomation for optimization.  The behavour of the GC
when encountering an object that is marked keystone but does not have
the keystone property is unspecified, and likely to be inconsistent.

=back

The Adjectives can be used meaningfully in the following ways.

=over 4

=item As a scalar variable taint.

my $item is GC::timely;

Whatever is stored within the scalar verable requires timely
collection.

=item As a taint on a collection.

my @array is GC::timely;

Each member of the @array requires timely collection.

=item As a taint on a value.

"A string" is GC::timely;    # Or should this be C<but CG:timely> ?
{a => "hash"} is GC::timely; # corrections/confirmation please.

The string/hash requires timely collection.

=item As a taint on a class or a role

class Philosopher is GC::timely {...}

The Philosopher object requires timely collection.

=item As a taint on a sub declaration.

sub ($x) is GC::timely {...}

The closure created by this sub requires timely collection.

=item As a Pragma

use GC::timely;

All objects are treated as timely while this is the current scope.

=back

=head1 PRAGMAS

=over

=item no GC::delay / use GC::delay

Requests that the GC avoid delay while this is the scope.  GCs that
don't induce delays may ignore this.  use GC::delay relaxes the
request within its lexical scope.

=item no GC::finalization / use GC::finalization

Requests that the GC not do any finalization while the program is
within this lexical scope.  Note the GC may detect and queue objects for
finalization, it's just not permitted to carry out finalization.

GC::delay and GC::destroy are orthogonal, setting them both to no
effectively disables the Garbage collector.

=item use GC::local

Requests that while this is the current scope, only objects who
have this as the origin scope are examined by the GC.

=back

=head1 SUBS 

=over

=item sub GC::delay(?Int $depth=1 --> Int|undef) {...}

Requests that GCs with delay run at this time.  For example a this
will trigger a mark and sweep style GCs mark and sweep operation.
GC::delay will cause a delay even in blocks marked no GC::delay.  The
meaning of the $depth is for the most part implementation specific,
with the following limitations.

=over

=item $depth==0

Requests an optional GC run.  That is the CG may run if the GC thinks
it's necessary ( This is equivalent to {use GC::delay} ).

=item $depth==1

Requests a normal GC run.

=item $depth>1

Requrests a more intensive GC run, with higher values
implying greater intensiveness.

=back

GC::delay may return the number of bytes freed.

=item sub GC::type(--> Str) {...}

Returns a string indicating the type of GC being used.

=back

=item sub GC::finalizate(Any $object --> Int|undef) {...}
=item sub GC::finalizate(Any $object, ?Bool $recursive --> Int|undef) {...}
=item sub GC::finalizate(+Any $object,+Bool $recursive --> Int|undef) {...}

Forcefully finalize $object, even if object is still in scope.  If
recursive is true then the GC will forcefully finalize everything that
$object points to.

=head1 METHODS

=over

=item method GC::new(::Class $class: --> GC) {...}

Returns a GC object permitting implementation specific requests.

=back

=cut