docs/dev/pccmethods.pod

   1 # Copyright (C) 2007, Parrot Foundation.
   2 # $Id$
   3
   4 =head1 NAME
   5
   6 docs/dev/pccmethods.pod - Parrot Calling Conventions in C
   7
   8 =head1 OVERVIEW
   9
  10 A C<PCCMETHOD> is a PMC method that follows Parrot Calling Conventions
  11 (a.k.a. PCC). This allows PIR code to call PMC methods using slurpy, named,
  12 and other types of arguments as specified in F<PDD03>. This offers flexibility
  13 not found in a PMC C<METHOD> or a vtable function using C calling conventions.
  14
  15 C<PCCINVOKE> is used to call a method using the Parrot Calling Conventions.
  16 It uses the standard find_method/invoke approach that the callmethodcc opcode
  17 would. You can use C<PCCINVOKE> in any PMC method (including v-table methods),
  18 even if they are not C<PCCMETHOD>s. You can call methods that are not
  19 implemented with C<PCCMETHOD>, too.
  20
  21
  22 =head1 SYNTAX
  23
  24 =head2 PCCMETHOD
  25
  26 To declare that a method in a PMC should take arguments using the Parrot
  27 Calling Conventions, prefix its name with the keyword C<PCCMETHOD>.
  28 Where you would put the C parameter list, put a PCC parameter list.
  29 Do not specify a return type for C<PCCMETHOD>s -- the true
  30 signature of the return is specified inside the method using C<RETURN>,
  31 described below.
  32
  33   PCCMETHOD PlayRandomSong() {
  34       ...
  35   }
  36
  37   PCCMETHOD PlaySong(STRING *artist, STRING *title) {
  38       ...
  39   }
  40
  41 For full details of the parameter list syntax, see L<Parameter List Syntax>.
  42
  43
  44 =head2 RETURN
  45
  46 To return arguments using the Parrot Calling Conventions, which you should do
  47 if you have implemented a C<PCCMETHOD> (unless it returns no arguments, of
  48 course), use the C<RETURN> keyword. This takes a signature as specified in
  49 the L<Parameter List Syntax> section.
  50
  51   RETURN(PMC *status, INTVAL count);
  52
  53
  54 =head2 PCCINVOKE
  55
  56 To call a method on an object using the Parrot Calling Conventions, use
  57 C<PCCINVOKE>. This takes 3 arguments, followed by the signature of the call
  58 and the arguments as specified in the L<Parameter List Syntax> section.
  59
  60 The first three arguments, in order, are:
  61
  62 =over 4
  63
  64 =item The current interpreter; use C<interp> in a PMC.
  65
  66 =item The object to call the method on. Use the C<SELF> macro for the
  67       current PMC.
  68
  69 =item The double-quoted name of the method to call.
  70
  71 =back
  72
  73 Any return arguments appear, with the return signature, to the left of the
  74 call and in parentheses.
  75
  76 For example:
  77
  78   PCCINVOKE(interp, monkey, "eat", PMC* banana);
  79
  80   (PMC *pooh) = PCCINVOKE(interp, monkey, "excrete");
  81
  82   (PMC *status, INTVAL count) = PCCINVOKE(interp, player, "PlaySong", artist, title);
  83
  84   PCCINVOKE(interp, SELF, value :named("key") :optional)
  85
  86
  87 =head2 Parameter List Syntax
  88
  89 The syntax for a PCC parameter list is a comma separated list of zero or more
  90 parameters. Each parameter takes the form:
  91
  92   { INTVAL | NUMVAL | STRING* | PMC* } NAME [ ADVERBS ]
  93
  94 That is, a register type, followed by a name, optionally followed by one or
  95 more flags specified as adverbs. The list of supported adverbs is listed in
  96 F<docs/pdds/pdd03_calling_conventions.pod>, the calling conventions design
  97 document.
  98
  99 Note that unlike PIR, single quotes B<cannot> be used to quote values
 100 in C-based PCC calls.
 101
 102 Also note that in line with the Parrot code standards, you should put the
 103 pointer symbol next to the variable,
 104
 105   PMC *param :optional
 106
 107 not next to the type.
 108
 109   PMC* param :optional
 110
 111
 112 =head1 OTHER CONSIDERATIONS
 113
 114 =head2 Performance
 115
 116 When a C<METHOD> or vtable function is called, C<NCI> is used to map the
 117 arguments held in the current Parrot_Context onto the C calling conventions.
 118 That is, you still end up involving the Parrot Calling Conventions anyway,
 119 so there is no reason to expect a C<PCCMETHOD> to be any slower. It may well
 120 be faster. It's probably best to just not care. :-)
 121
 122 It is clearly true that C<PCCINVOKE> is going to be more costly than an
 123 invocation of a C method from another C method, if you do the call directly at
 124 the C level. However, if you do that you are ignoring any method overrides if
 125 you have been subclassed, and you wouldn't want to do that now, would you?
 126
 127
 128 # vim: expandtab shiftwidth=2 tw=70:
 129