Coro/Coro/MakeMaker.pm

package Coro::MakeMaker;

use common::sense;

use Config;
use base 'Exporter';

our $installsitearch;

our $VERSION = 6.51;
our @EXPORT_OK = qw(&coro_args $installsitearch);

my %opt;

for my $opt (split /:+/, $ENV{PERL_MM_OPT}) {
   my ($k,$v) = split /=/, $opt;
   $opt{$k} = $v;
}

my $extra = $Config{sitearch};

$extra =~ s/$Config{prefix}/$opt{PREFIX}/ if
    exists $opt{PREFIX};

for my $d ($extra, @INC) {
   if (-e "$d/Coro/CoroAPI.h") {
      $installsitearch = $d;
      last;
   }
}

sub coro_args {
   my %arg = @_;
   $arg{INC} .= " -I$installsitearch/Coro";
   %arg;
}

1;
__END__

=head1 NAME

Coro::MakeMaker - MakeMaker glue for the XS-level Coro API

=head1 SYNOPSIS

This allows you to control coroutines from C/XS.

=head1 DESCRIPTION

For optimal performance, hook into Coro at the C-level. You'll need to
make changes to your C<Makefile.PL> and add code to your C<xs> / C<c>
file(s).

=head1 WARNING

When you hook in at the C-level you can get a I<huge> performance gain,
but you also reduce the chances that your code will work unmodified with
newer versions of C<perl> or C<Coro>. This may or may not be a problem.
Just be aware, and set your expectations accordingly.

=head1 HOW TO

=head2 Makefile.PL

  use Coro::MakeMaker qw(coro_args);

  # ... set up %args ...

  WriteMakefile (coro_args (%args));

=head2 XS

  #include "CoroAPI.h"

  BOOT:
    I_CORO_API ("YourModule");

=head2 API

This is just a small overview - read the Coro/CoroAPI.h header file in
the distribution, and check the examples in F<EV/> and F<Event/*>, or
as a more real-world example, the Deliantra game server (which uses
Coro::MakeMaker).

You can also drop me a mail if you run into any trouble.

 #define CORO_TRANSFER(prev,next) /* transfer from prev to next */
 #define CORO_SCHEDULE            /* like Coro::schedule */
 #define CORO_CEDE                /* like Coro::cede */
 #define CORO_CEDE_NOTSELF        /* like Coro::cede_notself */
 #define CORO_READY(coro)         /* like $coro->ready */
 #define CORO_IS_READY(coro)      /* like $coro->is_ready */
 #define CORO_NREADY              /* # of procs in ready queue */
 #define CORO_CURRENT             /* returns $Coro::current */
 #define CORO_THROW               /* exception pending? */
 #define CORO_READYHOOK           /* hook for event libs, see Coro::EV */

 /* C-level coroutine struct, opaque, not used much */
 struct coro;

 /* used for schedule-like-function prepares */
 struct coro_transfer_args
 {
   struct coro *prev, *next;
 };

 /* this is the per-perl-coro slf frame info */
 struct CoroSLF
 {
   void (*prepare) (pTHX_ struct coro_transfer_args *ta); /* 0 means not yet initialised */
   int (*check) (pTHX_ struct CoroSLF *frame);
   void *data; /* for use by prepare/check/destroy */
   void (*destroy) (pTHX_ struct CoroSLF *frame);
 };

 /* needs to fill in the *frame */
 typedef void (*coro_slf_cb) (pTHX_ struct CoroSLF *frame, CV *cv, SV **arg, int items);

 #define CORO_SV_STATE(coro)      /* returns the internal struct coro * */
 #define CORO_EXECUTE_SLF(cv,init,ax) /* execute a schedule-like function */
 #define CORO_EXECUTE_SLF_XS(init) /* SLF in XS, see e.g. Coro::EV */

 /* called on enter/leave */
 typedef void (*coro_enterleave_hook) (pTHX_ void *arg);

 #define CORO_ENTERLEAVE_HOOK(coro,enter,enter_arg,leave,leave_arg)   /* install an XS-level enter/leave hook */
 #define CORO_ENTERLEAVE_UNHOOK(coro,enter,leave)                     /* remove an XS-level enter/leave hook */
 #define CORO_ENTERLEAVE_SCOPE_HOOK(enter,enter_arg,leave,leave_arg)  /* install an XS-level enter/leave hook for the corrent scope */

=head1 AUTHOR/SUPPORT/CONTACT

   Marc A. Lehmann <schmorp@schmorp.de>
   http://software.schmorp.de/pkg/Coro.html

=cut
Revision:	1.76
Committed:	Sat Jun 25 19:04:04 2016 UTC (7 years, 11 months ago) by root
Branch:	MAIN
CVS Tags:	rel-6_51
Changes since 1.75:	+1 -1 lines
Log Message:	6.51
#	User	Rev	Content
1	root	1.1	package Coro::MakeMaker;
2
3	root	1.33	use common::sense;
4	root	1.2
5	root	1.1	use Config;
6			use base 'Exporter';
7
8	root	1.33	our $installsitearch;
9
10	root	1.76	our $VERSION = 6.51;
11	root	1.33	our @EXPORT_OK = qw(&coro_args $installsitearch);
12	root	1.1
13			my %opt;
14
15			for my $opt (split /:+/, $ENV{PERL_MM_OPT}) {
16			my ($k,$v) = split /=/, $opt;
17			$opt{$k} = $v;
18			}
19
20			my $extra = $Config{sitearch};
21
22			$extra =~ s/$Config{prefix}/$opt{PREFIX}/ if
23			exists $opt{PREFIX};
24
25			for my $d ($extra, @INC) {
26			if (-e "$d/Coro/CoroAPI.h") {
27			$installsitearch = $d;
28			last;
29			}
30			}
31
32			sub coro_args {
33			my %arg = @_;
34			$arg{INC} .= " -I$installsitearch/Coro";
35			%arg;
36			}
37
38			1;
39			__END__
40
41			=head1 NAME
42
43	root	1.19	Coro::MakeMaker - MakeMaker glue for the XS-level Coro API
44	root	1.1
45			=head1 SYNOPSIS
46
47	root	1.19	This allows you to control coroutines from C/XS.
48	root	1.1
49			=head1 DESCRIPTION
50
51	root	1.19	For optimal performance, hook into Coro at the C-level. You'll need to
52			make changes to your C<Makefile.PL> and add code to your C<xs> / C<c>
53			file(s).
54	root	1.1
55			=head1 WARNING
56
57	root	1.19	When you hook in at the C-level you can get a I<huge> performance gain,
58			but you also reduce the chances that your code will work unmodified with
59			newer versions of C<perl> or C<Coro>. This may or may not be a problem.
60			Just be aware, and set your expectations accordingly.
61	root	1.1
62			=head1 HOW TO
63
64			=head2 Makefile.PL
65
66			use Coro::MakeMaker qw(coro_args);
67
68			# ... set up %args ...
69
70	root	1.27	WriteMakefile (coro_args (%args));
71	root	1.1
72			=head2 XS
73
74			#include "CoroAPI.h"
75
76			BOOT:
77	root	1.27	I_CORO_API ("YourModule");
78	root	1.1
79	root	1.5	=head2 API
80	root	1.1
81	root	1.27	This is just a small overview - read the Coro/CoroAPI.h header file in
82			the distribution, and check the examples in F<EV/> and F<Event/*>, or
83			as a more real-world example, the Deliantra game server (which uses
84			Coro::MakeMaker).
85
86	root	1.67	You can also drop me a mail if you run into any trouble.
87
88	root	1.7	#define CORO_TRANSFER(prev,next) /* transfer from prev to next */
89	root	1.5	#define CORO_SCHEDULE /* like Coro::schedule */
90			#define CORO_CEDE /* like Coro::cede */
91	root	1.7	#define CORO_CEDE_NOTSELF /* like Coro::cede_notself */
92	root	1.5	#define CORO_READY(coro) /* like $coro->ready */
93	root	1.6	#define CORO_IS_READY(coro) /* like $coro->is_ready */
94			#define CORO_NREADY /* # of procs in ready queue */
95	root	1.5	#define CORO_CURRENT /* returns $Coro::current */
96	root	1.27	#define CORO_THROW /* exception pending? */
97			#define CORO_READYHOOK /* hook for event libs, see Coro::EV */
98
99	root	1.67	/* C-level coroutine struct, opaque, not used much */
100			struct coro;
101
102			/* used for schedule-like-function prepares */
103			struct coro_transfer_args
104			{
105			struct coro prev, next;
106			};
107
108			/* this is the per-perl-coro slf frame info */
109			struct CoroSLF
110			{
111			void (prepare) (pTHX_ struct coro_transfer_args ta); /* 0 means not yet initialised */
112			int (check) (pTHX_ struct CoroSLF frame);
113			void data; / for use by prepare/check/destroy */
114			void (destroy) (pTHX_ struct CoroSLF frame);
115			};
116
117			/* needs to fill in the frame /
118			typedef void (coro_slf_cb) (pTHX_ struct CoroSLF frame, CV cv, SV *arg, int items);
119
120	root	1.27	#define CORO_SV_STATE(coro) /* returns the internal struct coro * */
121			#define CORO_EXECUTE_SLF(cv,init,ax) /* execute a schedule-like function */
122			#define CORO_EXECUTE_SLF_XS(init) /* SLF in XS, see e.g. Coro::EV */
123	root	1.1
124	root	1.67	/* called on enter/leave */
125			typedef void (coro_enterleave_hook) (pTHX_ void arg);
126
127			#define CORO_ENTERLEAVE_HOOK(coro,enter,enter_arg,leave,leave_arg) /* install an XS-level enter/leave hook */
128			#define CORO_ENTERLEAVE_UNHOOK(coro,enter,leave) /* remove an XS-level enter/leave hook */
129			#define CORO_ENTERLEAVE_SCOPE_HOOK(enter,enter_arg,leave,leave_arg) /* install an XS-level enter/leave hook for the corrent scope */
130
131			=head1 AUTHOR/SUPPORT/CONTACT
132
133			Marc A. Lehmann <schmorp@schmorp.de>
134			http://software.schmorp.de/pkg/Coro.html
135
136	root	1.1	=cut