# Copyright (C) 2001-2014, Parrot Foundation.

=head1 NAME

docs/glossary.pod - Parrot Glossary

=head1 DESCRIPTION

Short descriptions of words and acronyms found in Parrot development.

=head1 VERSION

LAST UPDATED: 2014-06-17

glossary.pod is updated and maintained from Parrot's GitHub repository.
You may get the most up-to-date version at:
L<< https://github.com/parrot/parrot/docs/glossary.pod >>

=head1 GLOSSARY

=for comment
Please keep this file alphabetical.

=over 4

=item AST

Abstract Syntax Tree: a data structure typically generated by a language
parser.

=item bcg

Bytecode Generation: bcg will be part of the Parrot Compiler
tools. It will aid in converting POST to bytecode.

=item Continuations

Think of continuations as an execution "context". This context includes
everything local to that execution path, not just the stack. It is a snapshot
in time (minus global variables). While it is similar to C's C<setjmp> (taking
the continuation)/C<longjmp> (invoking the continuation), C<longjmp>'ing only
works "down" the stack; jumping "up" the stack (ie, back to a frame that has
returned) is bad. Continuations can work either way.

We can do two important things with continuations:

=over 4

=item 1

Create and pass a continuation object to a subroutine, which may recursively
pass that object up the call chain until, at some point, the continuation can
be called/executed to handle the final computation or return value. This is
pretty much tail recursion.

=item 2

Continuations can be taken at an arbitrary call depth, freezing the call chain
(context) at that point in time. If we save that continuation object into a
variable, we can later reinstate the complete context by its "handle". This
allows neat things like backtracking that aren't easily done in conventional
stacked languages, such as C. Since continuations represent "branches" in
context, it requires an environment that uses some combination of heap-based
stacks, stack trees and/or stack copying.

=back

It is common in a system that supports continuations to implement
L<co-routines|"Co-Routines"> on top of them.

A continuation is a sort of super-closure. When you take a continuation, it
makes a note of the current call stack and lexical scratchpads, along with the
current location in the code. When you invoke a continuation, the system drops
what it's doing, puts the call stack and scratchpads back, and jumps to the
execution point you were at when the continuation was taken. It is, in effect,
like you never left that point in your code.

Note that, like with closures, it only puts the B<scratchpads> back in scope -
it doesn't do anything with the values in the variables that are in those
scratchpads.

=item Co-Routines

Co-routines are virtually identical to normal subroutines, except while
subroutines always execute from their starting instruction to where they
return, co-routines may suspend themselves (or be suspended asynchronously if
the language permits) and resume at that point later. We can implement things
like "factories" with co-routines. If the co-routine never returns, every time
we call it, we "resume" the routine.

A co-routine is a subroutine that can stop in the middle, and start back up
later at the point you stopped. For example:

    sub sample : coroutine {
       print "A\n";
       yield;
       print "B\n";
       return;
    }

    sample();
    print "Foo!\n";
    sample();

will print

     A
     Foo!
     B

Basically, the C<yield> keyword says, "Stop here, but the next time we're
called, pick up at the next statement." If you return from a co-routine, the
next invocation starts back at the beginning.  Co-routines remember all their
state, local variables, and suchlike things.

=item COW

Copy On Write: a technique that copies strings lazily.

If you have a string A, and make a copy of it to get string B, the two strings
should be identical, at least to start. With COW, they are, because string A
and string B aren't actually two separate strings - they're the same string,
marked COW. If either string A or string B are changed, the system notes it and
only at that point does it make a copy of the string data and change it.

If the program never actually changes the string - something that's fairly
common - the program need never make a copy, saving both memory and time.

=item destruction

Destruction is low level memory clean up, such as calling C<free> on
C<malloc>ed memory.  This happens after L<"finalization">, and if resources are
adequate, may only happen as a side effect of program exit.

=item DOD

Dead Object Detection: the process of sweeping through all the objects,
variables, and whatnot inside of Parrot, and deciding which ones are in use and
which ones aren't. The ones that aren't in use are then freed up for later
reuse. (After they're destroyed, if active destruction is warranted.)

See also: L<"GC">

=item finalization

Finalization is high-level, user visible cleanup of objects, such as closing an
associated DB handle. Finalization reduces active objects down to passive
blocks of memory, but does not actually reclaim that memory. Memory is
reclaimed by the related L<"destruction"> operation, as and when necessary.

=item GC

Garbage Collection: the process of sweeping through all the active objects,
variables, and structures, marking the memory they're using as in use, and all
other memory is freed up for later reuse.

Garbage Collection and Dead Object Detection are separate in Parrot, since we
generally chew through memory segments faster than we chew through objects.
(This is a characteristic peculiar to Perl and other languages that do string
processing. Other languages chew through objects faster than memory)

See also: L<"DOD">

=item HLL

High-Level Language; Any of the languages that target the parrot virtual
machine.

=item ICU

International Components for Unicode

ICU is a C and C++ library that provides support for Unicode on a variety of
platforms. It was distributed with parrot at one time, but current releases
require you to get your own copy.

L<http://oss.software.ibm.com/icu/index.html>

=item IMCC

Intermediate Code Compiler: The component of parrot that compiles PASM
and PIR into bytecode.

See also L<"PIR">.

=item JAPH

Just another Parrot Hacker: or, a small script that generates that text.

=item MRO

Method resolution order

=item NCI

Native Call Interface: parrot's interface to native "C" libraries,
without a C-compiler.

=item NQP

Not Quite Perl (6):  designed to be a very small compiler for
quickly generating PIR routines to create transformers for Parrot (especially
HLL compilers).

See also L<"PCT">.

=item Packfile

Another name for a PBC file, due to the names used for data structures in one
of the early implementations in Perl 5.

=item PAST

Acronym for Parrot Abstract Syntax Tree, a set of classes that represent an
abstract syntax tree.

See also L<"PCT">.

=item PASM

Parrot Assembly Language is the lowest level language before being translated
in to bytecode.  Generally PIR is used.

=item PBC

Parrot bytecode. The name for the "executable" files that can be passed to the
Parrot interpreter for immediate execution (although PASM files can be
executed directly, too).

See also L<"Packfile">.

=item PCT

Parrot Compiler Toolkit: a complete set of tools and libraries
that are designed to create compilers targeting Parrot. The principal
components of PCT are PGE, PCT::HLLCompiler (a compiler driver), PAST classes,
POST classes, PCT::Grammar (a base class for PGE grammars).

In the ideal case, a language can be implemented by providing its parser
(using Perl 6 rules) which is generated by PGE, and providing a module written
in NQP that contains the I<actions> that are to be invoked during the parse.
These actions can then create the appropriate PAST nodes. A PAST to PIR
transformation already exists. Depending on the language, other phases can
be added, or overridden (for instance, the PAST to PIR transformation).

=item PDD

Parrot Design Document: documents that describe the features parrot must
implement.

See also L<< Running|http://docs.parrot.org/parrot/latest/html/docs/running.pod.html >> and
L<< PDD 0: Design Document Format|http://docs.parrot.org/parrot/latest/html/docs/pdds/pdd00_pdd.pod.html >>.

=item PGE

Parrot Grammar Engine.

See also L<"PCT">.

=item PIR

Parrot Intermediate Representation: A medium-level assembly language for Parrot
that hides messy details like register allocation so language compiler writers
who target Parrot don't have to roll their own. Files have the
extension C<.pir>.

=item PMC

Polymorphic Container:  these classes are the primitives that
HLLs use to represent their fundamental types, such as Perl's
scalar values.

=item Pod

The preferred format for all kinds of documentation in Parrot.

=item POST

Parrot Opcode Syntax Tree: A set of classes that represent opcodes.

See also L<"PCT">.

=item Predereferencing

A bytecode transformation technique which reduces the amount of pointer
dereferencing done in the inner loop of the interpreter by pre-converting
opcode numbers into pointers to their opfuncs, and also converting the register
numbers and constant numbers in the arguments to the ops into pointers.

=item run core

aka run loop, aka runcore. The way Parrot executes PBCs.
See L<docs/running.pod> for a list of available runcores, and how to tell
parrot which one to use.

=item SELF

The current object, PMC, which the current method is acting on.

=item SMOP

Simple Meta Object Protocol: A prototype object model written in PIR.

=item TGE

Tree Grammar Engine: a tool that can be used to generate tree transformers.

=item vtable

A table of operations attached to some data types, such as PMCs and strings.
Vtables are used to avoid using switches or long C<if> chains to handle
different data types.  They're similar to method calls, except that their names
are pre-selected, and there is no direct way to invoke them from PIR.

=item Warnock's Dilemma

The dilemma you face when posting a message to a public forum about something
and not even getting an acknowledgement of its existence. This leaves you
wondering if your problem is unimportant or previously addressed, if everyone is
waiting on someone else to answer you,  or if maybe your mail never actually
made it to anyone else in the forum.

=item Write Barrier

A write barrier is a function call to add the current PMC, usually SELF, to
the "root" (i.e. list) of garbage collected objects on the next GC. This is
needed in a destructive method call when a pointer to another garbage
collectable object is changed, and thus the content if the old object needs to
be recycled.

=back

=cut
