# Copyright (C) 2007, The Perl Foundation.
# $Id: pccmethods.pod 20567 2007-08-08 21:16:15Z particle $

=head1 NAME

docs/dev/pccmethods.pod - Parrot Calling Conventions in C

=head1 OVERVIEW

A C<PCCMETHOD> is a PMC method that follows Parrot Calling Conventions
(a.k.a. PCC). This allows PIR code to call PMC methods using slurpy, named,
and other types of arguments as specified in F<PDD03>. This offers flexibility
not found in a PMC C<METHOD> or a vtable method using C calling conventions.

C<PCCINVOKE> is used to call a method using the Parrot Calling Conventions.
It uses the standard find_method/invoke approach that the callmethodcc opcode
would. You can use C<PCCINVOKE> in any PMC method (including v-table methods),
even if they are not C<PCCMETHOD>s. You can call methods that are not
implemented with C<PCCMETHOD>, too.


=head1 SYNTAX

=head2 PCCMETHOD

To declare that a method in a PMC should take arguments using the Parrot
Calling Conventions, prefix its name with the keyword C<PCCMETHOD>.
Where you would put the C parameter list, put a PCC parameter list.
Do not specify a return type for C<PCCMETHOD>s -- the true
signature of the return is specified inside the method using C<PCCRETURN>,
described below.

  PCCMETHOD PlayRandomSong() {
      ...
  }

  PCCMETHOD PlaySong(STRING *artist, STRING *title) {
      ...
  }

For full details of the parameter list syntax, see L<Parameter List Syntax>.


=head2 PCCRETURN

To return arguments using the Parrot Calling Conventions, which you should do
if you have implemented a C<PCCMETHOD> (unless it returns no arguments, of
course), use the C<PCCRETURN> keyword. This takes a signature as specified in
the L<Parameter List Syntax> section.

  PCCRETURN(PMC *status, INTVAL count);


=head2 PCCINVOKE

To call a method on an object using the Parrot Calling Conventions, use
C<PCCINVOKE>. This takes 3 arguments, followed by the signature of the call
and the arguments as specified in the L<Parameter List Syntax> section.

The first three arguments, in order, are:

=over 4

=item The current interpreter; use C<interp> in a PMC.

=item The object to call the method on. Use the C<SELF> macro for the
      current PMC.

=item The double-quoted name of the method to call.

=back

Any return arguments appear, with the return signature, to the left of the
call and in parentheses.

For example:

  PCCINVOKE(interp, monkey, "eat", PMC* banana);

  (PMC *pooh) = PCCINVOKE(interp, monkey, "excrete");

  (PMC *status, INTVAL count) = PCCINVOKE(interp, player, "PlaySong", artist, title);

  PCCINVOKE(interp, SELF, value :named("key") :optional)


=head2 Parameter List Syntax

The syntax for a PCC parameter list is a comma separated list of zero or more
parameters. Each parameter takes the form:

  { INTVAL | NUMVAL | STRING* | PMC* } NAME [ ADVERBS ]

That is, a register type, followed by a name, optionally followed by one or
more flags specified as adverbs. The list of supported adverbs is listed in
F<docs/pdds/pdd03_calling_conventions.pod>, the calling conventions design
document.

Note that unlike PIR, single quotes B<cannot> be used to quote values
in C-based PCC calls.

Also note that in line with the Parrot code standards, you should put the
pointer symbol next to the variable,

  PMC *param :optional

not next to the type.

  PMC* param :optional


=head1 OTHER CONSIDERATIONS

=head2 Performance

When a C<METHOD> or vtable method is called, C<NCI> is used to map the
arguments held in the current Parrot_Context onto the C calling conventions.
That is, you still end up involving the Parrot Calling Conventions anyway,
so there is no reason to expect a C<PCCMETHOD> to be any slower. It may well
be faster. It's probably best to just not care. :-)

It is clearly true that C<PCCINVOKE> is going to be more costly than an
invocation of a C method from another C method, if you do the call directly at
the C level. However, if you do that you are ignoring any method overrides if
you have been subclassed, and you wouldn't want to do that now, would you?


# vim: expandtab shiftwidth=2 tw=70: