perl-docs-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From s...@apache.org
Subject cvs commit: modperl-docs/src/devel/core_explained core_explained.pod
Date Fri, 21 Dec 2001 16:54:20 GMT
stas        01/12/21 08:54:20

  Modified:    src/devel/core_explained core_explained.pod
  Log:
  - add a writeup on MP_INLINE vs C Macros vs Normal Functions
  
  Revision  Changes    Path
  1.10      +138 -0    modperl-docs/src/devel/core_explained/core_explained.pod
  
  Index: core_explained.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/devel/core_explained/core_explained.pod,v
  retrieving revision 1.9
  retrieving revision 1.10
  diff -u -r1.9 -r1.10
  --- core_explained.pod	2001/12/04 06:37:14	1.9
  +++ core_explained.pod	2001/12/21 16:54:20	1.10
  @@ -238,6 +238,7 @@
   name is just a prefix (I<mpxs_>, I<MPXS_>) the C function name is
   appended to it.
   
  +See the explanation about function naming and arguments passing.
   
   =item * Argspec
   
  @@ -296,6 +297,143 @@
     modperl_xs_sv_convert.h
     modperl_xs_typedefs.h
   
  +=head1 mpxs_ vs MPXS_
  +
  +If you look at the source code there are functions starting with
  +I<mpxs_> and those with I<MPXS_>.
  +
  +If you want to mess directly with the stack (i.e. without specifying
  +the prototype of the function), there are two ways to do that. Either
  +the function has to have a prototype C<...> (which stands for
  +I<items>, I<MARK> and I<SP> arguments) or prefixed with I<MPXS_>,
  +which are hooked directly into newXS().
  +
  +META: complete
  +
  +
  +=head1 MP_INLINE vs C Macros vs Normal Functions
  +
  +To make the code maintainable and reusable functions and macros are
  +used in when programming in C (and other languages :).
  +
  +When function is marked as I<inlined> it's merely a hint to the
  +compiler to replace the call to a function with the code inside this
  +function (i.e. inlined). Not every function can be inlined. Some
  +typical reasons why inlining is sometimes not done include:
  +
  +=over
  +
  +=item *
  +
  +the function calls itself, that is, is recursive
  +
  +=item *
  +
  +the function contains loops such as C<for(;;)> or C<while()>
  +
  +=item *
  +
  +the function size is too large
  +
  +=back
  +
  +Most of the advantage of inline functions comes from avoiding the
  +overhead of calling an actual function. Such overhead includes saving
  +registers, setting up stack frames, etc. But with large functions the
  +overhead becomes less important.
  +
  +Use the C<MP_INLINE> keyword in the declaration of the functions that
  +are to be inlined. The functions should be inlined when:
  +
  +=over
  +
  +=item *
  +
  +Only ever called once (the I<wrappers> that are called from I<.xs>
  +files), no matter what the size of code is.
  +
  +=item *
  +
  +Short bodies of code called in a I<hot> code (like
  +I<modperl_env_hv_store>, which is called many times inside of a loop),
  +where it is cleaner to see the code in function form rather than macro
  +with lots of C<\>'s. Remember that an inline function takes much more
  +space than a normal functions if called from many places in the code.
  +
  +=back
  +
  +Of course C macros are a bit faster then inlined functions, since
  +there is not even I<short jump> to be made, the code is literally
  +copied into the place it's called from. However using macros comes at
  +a price:
  +
  +=over
  +
  +=item *
  +
  +Also unlike macros, in functions argument types are checked, and
  +necessary conversions are performed correctly. With macros it's
  +possible that weird things will happen if the caller has passed
  +arguments of the wrong type when calling a macro.
  +
  +=item *
  +
  +One should be careful to pass only absolute values as I<"arguments">
  +to macros. Consider a macro that returns an absolute value of the
  +passed argument:
  +
  +  #define ABS(v) ( (v) >= 0 ? (v) : -(v) )
  +
  +In our example if you happen to pass a function it will be called
  +twice:
  +
  +  abs_val = ABS(f());
  +
  +Since it'll be extended as:
  +
  +  abs_val = f() >= 0 ? f() : -f();
  +
  +You cannot do simple operation like increment--in our example it will
  +be called twice:
  +
  +  abs_val = ABS(i++);
  +
  +Because it becomes:
  +
  +  abs_val = i++ >= 0 ? i++ : -i++;
  +
  +=item *
  +
  +It's dangerous to use the if() condition without enclosing the code in
  +C<{}>, since the macro may be called from inside another if-else
  +condition, which may cause the else part called if the if() part from
  +the macro fails.
  +
  +But we always use C<{}> for the code inside the if-else condition, so
  +it's not a problem here.
  +
  +=item *
  +
  +A multi-line macro can cause problems if someone uses the macro in a
  +context that demands a single statement.
  +
  +  while (foo) MYMACRO(bar);
  +
  +But again, we always enclose any code in conditional with C<{}>, so
  +it's not a problem for us.
  +
  +=item *
  +
  +Inline functions present a problem for debuggers and profilers,
  +because the function is expanded at the point of call and loses its
  +identity. This makes the debugging process a nightmare.
  +
  +A compiler will typically have some option available to disable
  +inlining.
  +
  +=back
  +
  +In all other cases use normal functions.
   
   
   
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-cvs-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-cvs-help@perl.apache.org


Mime
View raw message