Permalink
Browse files

Renamed docs/dev/pccmethods.pod to docs/dev/pcc_methods.pod so that i…

…t is more consistent with docs/dev/pcc_state.pod.
  • Loading branch information...
1 parent f74dd8b commit 94cbd48cc1702acba1f595ac1a54d19ac49882f2 @soh-cah-toa soh-cah-toa committed Sep 27, 2011
Showing with 38 additions and 33 deletions.
  1. +1 −1 MANIFEST
  2. +37 −32 docs/dev/{pccmethods.pod → pcc_methods.pod}
View
@@ -302,8 +302,8 @@ docs/dev/infant.pod [doc]
docs/dev/longopt.pod [doc]
docs/dev/optimizer.pod [doc]
docs/dev/parrot_api.pod [doc]
+docs/dev/pcc_methods.pod [doc]
docs/dev/pcc_state.pod [doc]
-docs/dev/pccmethods.pod [doc]
docs/dev/pmc_freeze.pod [doc]
docs/dev/pmc_obj_design_meeting_notes.pod [doc]
docs/dev/profiling.pod [doc]
@@ -1,31 +1,30 @@
-# Copyright (C) 2007, Parrot Foundation.
+# Copyright (C) 2007-2011, Parrot Foundation.
=head1 NAME
-docs/dev/pccmethods.pod - Parrot Calling Conventions in C
+docs/dev/pcc_methods.pod - Parrot Calling Conventions in C
=head1 OVERVIEW
-A C<PCCMETHOD> is a PMC method that follows Parrot Calling Conventions
+A C<PCCMETHOD> is a PMC method that follows the 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
+and other types of arguments as specified in I<PDD03>. This offers flexibility
not found in a PMC C<METHOD> or a vtable function 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.
-
+It uses the standard C<find_method()>/C<invoke()> approach that the
+C<callmethodcc> opcode would. You can use C<PCCINVOKE> in any PMC method
+(including vtable 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
+=head2 C<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
+The PCC parameter list is put where you would normally put the C
+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<RETURN>,
described below.
@@ -39,8 +38,7 @@ described below.
For full details of the parameter list syntax, see L<Parameter List Syntax>.
-
-=head2 RETURN
+=head2 C<RETURN>
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
@@ -49,23 +47,28 @@ the L<Parameter List Syntax> section.
RETURN(PMC *status, INTVAL count);
-
-=head2 PCCINVOKE
+=head2 C<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
+C<PCCINVOKE>. It 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 current interpreter; use C<interp> in a PMC.
+
+=item *
-=item The object to call the method on. Use the C<SELF> macro for the
- current PMC.
+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.
+=item *
+
+The double-quoted name of the method to call.
=back
@@ -82,7 +85,6 @@ For example:
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
@@ -95,34 +97,37 @@ 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
+Note that unlike PIR, single quotes I<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
+ PMC *param :optional # Good
not next to the type.
- PMC* param :optional
-
+ PMC* param :optional # Bad
=head1 OTHER CONSIDERATIONS
=head2 Performance
When a C<METHOD> or vtable function is called, C<NCI> is used to map the
-arguments held in the current Parrot_Context onto the C calling conventions.
+arguments held in the current C<Parrot_Context> into 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?
-
+invocation of a C function from another C function, 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:
+=cut
+__END__
+Local Variables:
+ fill-column:78
+End:
+vim: expandtab shiftwidth=4:

0 comments on commit 94cbd48

Please sign in to comment.