<commit_before># Copyright: 2001-2005 The Perl Foundation.  All Rights Reserved.
# $Id$

=head1 NAME

PIR - calling conventions

=head1 VERSION

=over 4

=item 0.1 initial proposal

=item 0.2 initial, checked in

=item 0.3 updated parrot calling conventions and invoke

=item 0.4 methods and shortcuts documented

=back

=head1 OVERVIEW

This document describes subroutine and method calling conventions.

=head1 DESCRIPTION

As imcc does register allocation, it has to track the life span of
variables. This includes the (possible) data flow in and out of
subroutines.

=head1 Parrot calling conventions - CPS

=head2 Explicitely Calling PASM Subroutines

  newsub $P0, .Sub, _sub_label
  newsub $P1, .Continuation, ret_addr
  ...
  .pcc_begin prototyped|non_prototyped
  .arg x	# I5
  .arg y	# I6
  .arg z	# I7
  .pcc_call $P0, $P1	# r = _sub_label(x, y, z)
  ret_addr:
  .local int r  # optional - new result var
  .result r
  .pcc_end

=head2 The Short Way

  ...  # variable decls
  r = _sub_label(x, y, z)
  (r1[, r2 ...]) = _sub_label(x, y, z)
  _sub_label(x, y, z)

Instead of the label a Subroutine object can be used too:

   find_global $P0, "_sub_label"
   $P0(args)

=head2 Subroutines

  .sub _sub_label [Subpragma, ...]
   .param int a # I5
   .param int b # I6
   .param int c # I7
  ...
  .pcc_begin_return
   .return xy   # e.g. I5
  .pcc_end_return
  ...
  .end

An alternative syntaxs allow to express a return in one line.
The surrounded parentheses are mandatory. Besides making
sequence break more conspiscuous, this is necessary to
distinguish this syntax from other uses of the .return directive
that will be probably deprecated.

  .return ( a, b )      # return the values of a and b

  .return ()            # return no value

  .return func_call()   # tail call function

  .return o."meth"()    # tail method call

Similarly, one can yield using the .yield directive

  .yield ( a, b )      # yield with the values of a and b

  .yield ()            # yield with no value


=head2 Subpragma

This is a comma separated list of zero or more items with the
following meaning:

=over 4

=item * B<prototyped>, B<non_prototyped>

Specify calling convention

=item * @MAIN

Define "main" entry point to start execution. If multiple subroutines
are marked as B<@MAIN>, the B<last> marked subroutine is entered.

=item * @LOAD

Run this subroutine during the B<load_library> opcode.
B<@LOAD> is ignored, if another subroutine in that file is marked with
B<@MAIN>.

=item * @ANON

Do not install this subroutine in the namespace. Allows the subroutine
name to be reused.

=item * method

Declare subroutine being a method.

=back

Notes:

=over 4

=item * B<prototyped>, B<non_prototyped>

If a subroutine definition has no prototyped specifier, code gets
emitted to receive parameters by both flavors.

=item * B<newsub>

Currently needs the B<.Class> syntax, i.e. a B<dot> in front of the
class name.

=item * B<pcc_call>

Takes either 2 arguments: the sub and the return continuation, or the
sub only. For the latter case an B<invokecc> gets emitted. Providing
an explicit return continuation is more efficient, if its created
outside of a loop and the call is done inside a loop.

=item * Saved Regs:

Only the top half of registers are preserved currently.<commit_msg>* imcc: document @MULTI.<commit_after># Copyright: 2001-2005 The Perl Foundation.  All Rights Reserved.
# $Id$

=head1 NAME

PIR - calling conventions

=head1 VERSION

=over 4

=item 0.1 initial proposal

=item 0.2 initial, checked in

=item 0.3 updated parrot calling conventions and invoke

=item 0.4 methods and shortcuts documented

=back

=head1 OVERVIEW

This document describes subroutine and method calling conventions.

=head1 DESCRIPTION

As imcc does register allocation, it has to track the life span of
variables. This includes the (possible) data flow in and out of
subroutines.

=head1 Parrot calling conventions - CPS

=head2 Explicitely Calling PASM Subroutines

  newsub $P0, .Sub, _sub_label
  newsub $P1, .Continuation, ret_addr
  ...
  .pcc_begin prototyped|non_prototyped
  .arg x	# I5
  .arg y	# I6
  .arg z	# I7
  .pcc_call $P0, $P1	# r = _sub_label(x, y, z)
  ret_addr:
  .local int r  # optional - new result var
  .result r
  .pcc_end

=head2 The Short Way

  ...  # variable decls
  r = _sub_label(x, y, z)
  (r1[, r2 ...]) = _sub_label(x, y, z)
  _sub_label(x, y, z)

Instead of the label a Subroutine object can be used too:

   find_global $P0, "_sub_label"
   $P0(args)

=head2 Subroutines

  .sub _sub_label [Subpragma, ...]
   .param int a # I5
   .param int b # I6
   .param int c # I7
  ...
  .pcc_begin_return
   .return xy   # e.g. I5
  .pcc_end_return
  ...
  .end

An alternative syntaxs allow to express a return in one line.
The surrounded parentheses are mandatory. Besides making
sequence break more conspiscuous, this is necessary to
distinguish this syntax from other uses of the .return directive
that will be probably deprecated.

  .return ( a, b )      # return the values of a and b

  .return ()            # return no value

  .return func_call()   # tail call function

  .return o."meth"()    # tail method call

Similarly, one can yield using the .yield directive

  .yield ( a, b )      # yield with the values of a and b

  .yield ()            # yield with no value


=head2 Subpragma

This is a comma separated list of zero or more items with the
following meaning:

=over 4

=item * B<prototyped>, B<non_prototyped>

Specify calling convention

=item * @MAIN

Define "main" entry point to start execution. If multiple subroutines
are marked as B<@MAIN>, the B<last> marked subroutine is entered.

=item * @LOAD

Run this subroutine during the B<load_library> opcode.
B<@LOAD> is ignored, if another subroutine in that file is marked with
B<@MAIN>.

=item * @ANON

Do not install this subroutine in the namespace. Allows the subroutine
name to be reused.

=item * @MULTI(Type1, Type2...)

Engage in multiple dispatch with the listed types.

=item * method

Declare subroutine being a method.

=back

Notes:

=over 4

=item * B<prototyped>, B<non_prototyped>

If a subroutine definition has no prototyped specifier, code gets
emitted to receive parameters by both flavors.

=item * B<newsub>

Currently needs the B<.Class> syntax, i.e. a B<dot> in front of the
class name.

=item * B<pcc_call>

Takes either 2 arguments: the sub and the return continuation, or the
sub only. For the latter case an B<invokecc> gets emitted. Providing
an explicit return continuation is more efficient, if its created
outside of a loop and the call is done inside a loop.

=item * Saved Regs:

Only the top half of registers are preserved currently.
{'fraction_non_alphanumeric': 0.07839616995810891, 'fraction_numerical': 0.013464991023339317, 'mean_word_length': 3.3437296946068877, 'pattern_counts': {'":': 0, '<': 31, '<?xml version=': 0, '>': 31, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3809974', 'n_tokens_mistral': 2332, 'n_tokens_neox': 2177, 'n_words': 943}