Index

This file was automatically generated from http://svn.pugscode.org/pugs/docs/notes/GC.pod on Wed Jun 6 22:16:47 2007 GMT, revision 16639.

GC

• NAME
• SYNOPSIS
• DEFINITIONS
• ADJECTIVES
• PRAGMAS
• SUBS

NAME

GC - The interface to the runtime Garbage collector.

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($_)} }

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.

origin scope

The lexical scope where an object was created.

current scope

The lexical scope where this thread is currently executing.

priority

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

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.

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.

finalization

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

ADJECTIVES

The GC API supplies the following adjectives.

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.

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.

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.

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.

The Adjectives can be used meaningfully in the following ways.

As a scalar variable taint.

my $item is GC::timely;

Whatever is stored within the scalar verable requires timely collection.

As a taint on a collection.

my @array is GC::timely;

Each member of the @array requires timely collection.

As a taint on a value.

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

The string/hash requires timely collection.

As a taint on a class or a role

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

The Philosopher object requires timely collection.

As a taint on a sub declaration.

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

The closure created by this sub requires timely collection.

As a Pragma

use GC::timely;

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

PRAGMAS

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.

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.

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.

SUBS

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.

$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} ).

$depth==1

Requests a normal GC run.

$depth>1

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

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

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

Returns a string indicating the type of GC being used.