[ViewVC] Diff of: cvs/Coro-Multicore/perlmulticore.h

Comparing Coro-Multicore/perlmulticore.h (file contents):
Revision 1.1 by root, Sat Jun 27 19:32:15 2015 UTC vs.
Revision 1.8 by root, Sun Jun 28 18:37:52 2015 UTC

-TODO: if () acquire example
 /*
  * Author: Marc A. Lehmann <xsthreadpool@schmorp.de>
  * License: public domain, or where this is not possible/at your option,
  *          CC0 (https://creativecommons.org/publicdomain/zero/1.0/)
  */
 #ifndef PERL_MULTICORE_H
 #define PERL_MULTICORE_H
-#if 0
+/*
 =head1 NAME
-perlmulticore.h - release the perl interpreter for other uses while doing hard work
+perlmulticore.h - the Perl Multicore Specification and Implementation
 =head1 SYNOPSIS
   #include "perlmultiore.h"
 The design goals for this mechanism were to be simple to use, very
 efficient when not needed, low code and data size overhead and broad
 applicability.
+The newest version of this document can be found at
+L<http://pod.tst.eu/http://cvs.schmorp.de/Coro-Multicore/perlmulticore.h>.
+The newest version of the header file itself, which
+includes this documentation, can be downloaded from
+L<http://cvs.schmorp.de/Coro-Multicore/perlmulticore.h>.
 =head1 HOW DO I USE THIS IN MY MODULES?
-The suage is very simple - you include this header file in your XS module. Then, before you
+The usage is very simple - you include this header file in your XS module. Then, before you
 do your lengthy operation, you release the perl interpreter:
    perlinterp_release ();
 And when you are done with your computation, you acquire it again:
    perlinterp_acquire ();
 And that's it. This doesn't load any modules and consists of only a few
-machine instructions when no module tot ake advantage of it is loaded.
+machine instructions when no module to take advantage of it is loaded.
 Here is a simple example, an C<flock> wrapper implemented in XS. Unlike
 perl's built-in C<flock>, it allows other threads (for example, those
 provided by L<Coro>) to execute, instead of blocking the whole perl
 interpreter. For the sake of this example, it requires a file descriptor
 instead of a handle.
-   #include "perlmulticore.h" /* this header file */
+   #include "perlmulticore.h" // this header file
    // and in the XS portion
    int flock (int fd, int operation)
            CODE:
            perlinterp_release ();
 =head2 HOW ABOUT NOT-SO LONG WORK?
 Sometimes you don't know how long your code will take - in a compression
 library for example, compressing a few hundred Kilobyte of data can take
-a while, while 50 Bytes will comptess so fast that even attempting to do
+a while, while 50 Bytes will compress so fast that even attempting to do
 something else could be more costly than just doing it.
 This is a very hard problem to solve. The best you can do at the moment is
 to release the perl interpreter only when you think the work to be done
 justifies the expense.
 Make sure the if conditions are exactly the same and don't change, so you
 always call acquire when you release, and vice versa.
 When you don't have a handy indicator, you might still do something
 useful. For example, if you do some file locking with C<fcntl> and you
-expect the lock to be available immediatelly in most cases, you could try
+expect the lock to be available immediately in most cases, you could try
 with C<F_SETLK> (which doesn't wait), and only release/wait/acquire when
 the lock couldn't be set:
    int res = fcntl (fd, F_SETLK, &flock);
    if (res)
      {
        // error, assume lock is held by another process and do it the slow way
        perlinterp_release ();
        res = fcntl (fd, F_SETLKW, &flock);
-       perlinterp_release ();
+       perlinterp_acquire ();
      }
 =head1 THE HARD AND FAST RULES
 As with everything, there are a number of rules to follow.
    if (!function_that_fails_with_0_return_value ())
      {
        perlinterp_acquire ();
        croak ("error");
+       // croak doesn't return
      }
    perlinterp_acquire ();
    // do other stuff
 thread-safe, too.
 Always assume that the code between C<perlinterp_release> and
 C<perlinterp_acquire> is executed in parallel on multiple CPUs at the same
 time. If your code can't cope with that, you could consider using a mutex
-to only allow one such execution, which is sitll better than blocking
+to only allow one such execution, which is still better than blocking
 everybody else from doing anything:
    static pthread_mutex_t my_mutex = PTHREAD_MUTEX_INITIALIZER;
    perlinterp_release ();
    pthread_mutex_lock (&my_mutex);
    do_your_non_thread_safe_thing ();
    pthread_mutex_unlock (&my_mutex);
    perlinterp_acquire ();
-This isn't as trivial as it looks though, as you need to find out which
-threading system is in use (with L<Coro::Multicore>, it currently is
-always pthreads).
 =item I<Don't> get confused by having to release first.
 In many real world scenarios, you acquire a resource, do something, then
 release it again. Don't let this confuse you, with this, you already own
 the resource (the perl interpreter) so you have to I<release> first, and
 =over 4
 =item Simple to Use
 All you have to do is identify the place in your existing code where you
-stop touching perl stuff, do your actual work, and strat touching perl
+stop touching perl stuff, do your actual work, and start touching perl
 stuff again.
 Then slap C<perlinterp_release ()> and C<perlinterp_acquire ()> around the
 actual work code.
 first are two memory accesses and a predictable function call of an empty
 function.
 Of course, the overhead is much higher when these functions actually
 implement anything useful, but you always get what you pay for.
+With L<Coro::Multicore>, every release/acquire involves two pthread
+switches, two coro thread switches, a bunch of syscalls, and sometimes
+interacting with the event loop.
+A dedicated thread pool such as the one L<IO::AIO> uses could reduce
+these overheads, and would also reduce the dependencies (L<AnyEvent> is a
+smaller and more portable dependency than L<Coro>), but it would require a
+lot more work on the side of the module author wanting to support it than
+this solution.
 =item Low Code and Data Size Overhead
 On a 64 bit system, F<perlmulticore.h> uses exactly C<8> octets (one
 pointer) of your data segment, to store the C<perl_multicore_api>
 octet sequence:
    150>   mov    0x200f23(%rip),%rax  # <perl_multicore_api>
    157>   callq  *0x8(%rax)
-amd64 code sure is bloated.
 The biggest part if the initialisation code, which consists of 11 lines of
 typical XS code. On my system, all the code in F<perlmulticore.h> compiles
 to less than 160 octets of read-only data.
 =item Broad Applicability
 efficient when not needed, low code and data size overhead and broad
 applicability.
 =back
+=head1 DISABLING PERL MULTICORE AT COMPILE TIME
+You can disable the complete perl multicore API by defining the
+symbol C<PERL_MULTICORE_DISABLE> to C<1> (e.g. by specifying
+F<-DPERL_MULTICORE_DISABLE> as compiler argument).
+This will leave no traces of the API in the compiled code, suitable
+"empty" C<perl_release> and C<perl_acquire> definitions will be provided.
+This could be added to perl's C<CPPFLAGS> when configuring perl on
+platforms that do not support threading at all for example.
 =head1 AUTHOR
    Marc A. Lehmann <perlmulticore@schmorp.de>
+   http://perlmulticore.schmorp.de/
 =head1 LICENSE
-The F<perlmulticore.h> is put into the public domain. Where this is legally
+The F<perlmulticore.h> header file is put into the public
+domain. Where this is legally not possible, or at your
-not possible, or at your option, it can be licensed under creativecommons
+option, it can be licensed under creativecommons CC0
-CC0 license: L<https://creativecommons.org/publicdomain/zero/1.0/>.
+license: L<https://creativecommons.org/publicdomain/zero/1.0/>.
 =cut
-#endif
+*/
+#if PERL_MULTICORE_DISABLE
+#define perlinterp_release() do { } while (0)
+#define perlinterp_acquire() do { } while (0)
+#else
+/* this struct is shared between all modules, and currently */
+/* contain only the two function pointers for release/acquire */
 struct perl_multicore_api
 {
   void (*pmapi_release)(void);
   void (*pmapi_acquire)(void);
 };
    = (struct perl_multicore_api *)&perl_multicore_api_init;
 #define perlinterp_release() perl_multicore_api->pmapi_release ()
 #define perlinterp_acquire() perl_multicore_api->pmapi_acquire ()
+/* this is the release/acquire implementation used as fallback */
 static void
 perl_multicore_nop (void)
 {
 }
+/* this is the initial implementation of "release" - it initialises */
+/* the api and then calls the real release function */
 static void
 perl_multicore_init (void)
 {
   dTHX;
   /* call the real (or dummy) implementation now */
   perlinterp_release ();
 }
 #endif
+#endif

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing Coro-Multicore/perlmulticore.h (file contents): Revision 1.1 by root, Sat Jun 27 19:32:15 2015 UTC vs. Revision 1.8 by root, Sun Jun 28 18:37:52 2015 UTC

Diff Legend

Comparing Coro-Multicore/perlmulticore.h (file contents):
Revision 1.1 by root, Sat Jun 27 19:32:15 2015 UTC vs.
Revision 1.8 by root, Sun Jun 28 18:37:52 2015 UTC