/ 
parrot-0.8.0
/ docs/dev/pccmethods.pod

NAME

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

OVERVIEW

A 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 PDD03. This offers flexibility not found in a PMC METHOD or a vtable method using C calling conventions.

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 PCCINVOKE in any PMC method (including v-table methods), even if they are not PCCMETHODs. You can call methods that are not implemented with PCCMETHOD, too.

SYNTAX

PCCMETHOD

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

PCCMETHOD PlayRandomSong() {
    ...
}

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

For full details of the parameter list syntax, see "Parameter List Syntax".

RETURN

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

RETURN(PMC *status, INTVAL count);

PCCINVOKE

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

The first three arguments, in order, are:

The current interpreter; use interp in a PMC.
The object to call the method on. Use the SELF macro for the current PMC.
The double-quoted name of the method to call.

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)

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 docs/pdds/pdd03_calling_conventions.pod, the calling conventions design document.

Note that unlike PIR, single quotes 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

OTHER CONSIDERATIONS

Performance

When a METHOD or vtable method is called, 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 PCCMETHOD to be any slower. It may well be faster. It's probably best to just not care. :-)

It is clearly true that 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: