---

inline.h File Reference

Defines a set of macros used to be used when defining inlines. More...

---

Detailed Description

Defines a set of macros used to be used when defining inlines.

Author:

JJRussell - russell@slac.stanford.edu

MOTIVATION
Unfortunately there does not seem to be agreement on how to specify inline functions and their prototypes across the various compilers. In addition, compilers treat inlines differently depending on whether optimization is enabled or not.

These files define 8 symbols to aid the user in supporting inline functions over multiple targets.

USAGE
There are two set of definitions. One for the prototype declarations and one for the actual function definitions. These definitions are definitions are dependent on whether this is included in the implementation file or a user file. Here implementation file is meant to be a file whose sole existence is to create a callable version of the inlines. This is necessary because some compilers (gcc, for example) will not inline under some circumstances (for example, when the optimization level is set to 0). Instead, an external call to the 'inlined' routine is generated. The 'implementation file is used to generate a callable copy of these routine in this case. Unfortunately, the declarations of the inlines is different than in normal user code. Hence, one has two sets of definitions, one for normal usage and one used only in the implementation file.

See the example below for procedure that works even when one is mixing inlines with other inlines, whether in implementation files or in user code.

SYMBOLS DEFINED

SET1 - USED in implementation files.

 INLINE_IMP_EXT_PROTO- Declares prototypes, inlines with public interfaces.
 INLINE_IMP_EXT_FNC  - Declares public inline functions.                   
 INLINE_IMP_PROTO    - Declares prototypes, inlines with private interfaces.
 INLINE_IMP_FNC      - Declares private inline functions.                   

SET 2 - USED in USER programs.

 INLINE_USR_EXT_PROTO- Declares prototypes, inlines with public interfaces.
 INLINE_USR_EXT_FNC  - Declares public inline functions.                   
 INLINE_USR_PROTO    - Declares prototypes, inlines with private interfaces.
 INLINE_USR_FNC      - Declares private inline functions.                   

EXAMPLE
Suppose one wishes to create an inline version of a routine which adds or subtracts 2 integers. One would create the interface include file MTH.ih.

In order to be able to include one set of inlines in another set, one must make sure that each has the proper declarations. The following procedure works.
#ifndef MTH_IH
#define MTH_IH

#include "BBC/inline.h"


The following correctly defines the symbols properly for both USER includes and implementation file includes. The convention adopted here is that the implementation file will define the symbol MTH_IMPLEMENTATION_FILE

#ifdef MTH__IMPLEMENTATION_FILE

      #define MTH__EXT_PROTO INLINE_IMP_EXT_PROTO
      #define MTH__EXT_FNC   INLINE_IMP_EXT_FNC  
      #define MTH__LCL_PROTO INLINE_IMP_LCL_PROTO
      #define MTH__LCL_FNC   INLINE_IMP_LCL_FNC
      

#else

     
      #define MTH__EXT_PROTO INLINE_USR_EXT_PROTO 
      #define MTH__EXT_FNC   INLINE_USR_EXT_FNC   
      #define MTH__LCL_PROTO INLINE_USR_LCL_PROTO 
      #define MTH__LCL_FNC   INLINE_USR_LCL_FNC
     

#endif

      / * Declare the prototypes  * /             
      MTH__EXT_PROTO int MTH__add (int a, int b); 
      MTH__EXT_PROTO int MTH__sub (int a, int b); 
      MTH__LCL_PROTO int mth__add (int a, int b);
      

      / * Drop the implementations * /
      MTH__EXT_FNC   int MTH_add (int a, int b) 
      {
         return mth__add (a, b);                    \n
      }

                                                    
      MTH__EXT_FNC   int MTH_sub (int a, int b)
      {
      return mth__add (a, -b);
      }

                                           
      MTH__LCL_FNC   int mth__add (int a, int b)
      {
         return a + b;
      }

The user of this facility would then do

                                           
     #include MTH.ih

      int myTest (a, b)
      {
          printf ("The sum of %d + %d = %d\n", a, b, MTH__add (a, b));
          printf ("The dif of %d - %d = %d\n", a, b, MTH__sub (a, b));
      }

If one wishes to produce a more traditional callable interface, then define the interface file MTH.h

      #ifndef MTH_H
      #define MTH_H

      / * Define the prototypes * /
      int MTH_add (int a, int b);
      int MTH_sub (int a, int b);


      #endif
      

and the implementation file MTH.c

      

      #include "BBC/alias.h"
      #include "BBC/inline.h"
                             
      #define   MTH__IMPLEMENTATION_FILE   -- This is the implementation file
      #include "BBC/MTH.ih"                -- Makes callable versions of     
                                           -- MTH__add and MTH__sub

      ALIAS_BEG (MTH)                      -- This aliases ...               
      ALIAS_FNC (MTH__add, MTH_add)        -- ...  MTH_add with MTH__add     
      ALIAS_FNC (MTH__sub, MTH_sub)        -- ...  MTH_sub with MTH__sub     
      ALIAS_END (MTH)

This scheme allows the user to mix and match between callable and inline versions. In this example the MTH__xxx routines are the inlines and the MTH_xxx are the callable versions.

---