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

Comparing Coro-Multicore/perlmulticore.h (file contents):
Revision 1.2 by root, Sat Jun 27 19:36:39 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"
 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 nwest version of the header fgile itself, which
+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?
 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 ();
    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.
    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
 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>
 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.2 by root, Sat Jun 27 19:36:39 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.2 by root, Sat Jun 27 19:36:39 2015 UTC vs.
Revision 1.8 by root, Sun Jun 28 18:37:52 2015 UTC