Apache Portable Runtime
apr_hooks.h
Go to the documentation of this file.
00001 /* Licensed to the Apache Software Foundation (ASF) under one or more
00002  * contributor license agreements.  See the NOTICE file distributed with
00003  * this work for additional information regarding copyright ownership.
00004  * The ASF licenses this file to You under the Apache License, Version 2.0
00005  * (the "License"); you may not use this file except in compliance with
00006  * the License.  You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #ifndef APR_HOOKS_H
00018 #define APR_HOOKS_H
00019 
00020 #include "apu.h"
00021 /* For apr_array_header_t */
00022 #include "apr_tables.h"
00023 
00024 /**
00025  * @file apr_hooks.h
00026  * @brief Apache hook functions
00027  */
00028 
00029 #ifdef __cplusplus
00030 extern "C" {
00031 #endif
00032 /**
00033  * @defgroup APR_Util_Hook Hook Functions
00034  * @ingroup APR
00035  * @{
00036  */
00037 
00038 /**
00039  * @defgroup apr_hook_probes Hook probe capability
00040  * APR hooks provide a trace probe capability for capturing
00041  * the flow of control and return values with hooks.
00042  *
00043  * In order to use this facility, the application must define
00044  * the symbol APR_HOOK_PROBES_ENABLED and the four APR_HOOK_PROBE_
00045  * macros described below before including apr_hooks.h in files
00046  * that use the APR_IMPLEMENT_EXTERNAL_HOOK_* macros.
00047  *
00048  * This probe facility is not provided for APR optional hooks.
00049  * @{
00050  */
00051 
00052 #ifdef APR_HOOK_PROBES_ENABLED
00053 #define APR_HOOK_INT_DCL_UD void *ud = NULL
00054 #else
00055 /** internal implementation detail to avoid the ud declaration when
00056  * hook probes are not used
00057  */
00058 #define APR_HOOK_INT_DCL_UD
00059 /**
00060  * User-defined hook probe macro that is invoked when the hook
00061  * is run, before calling any hook functions.
00062  * @param ud A void * user data field that should be filled in by
00063  * this macro, and will be provided to the other hook probe macros.
00064  * @param ns The namespace prefix of the hook functions
00065  * @param name The name of the hook
00066  * @param args The argument list to the hook functions, with enclosing
00067  * parens.
00068  */
00069 #define APR_HOOK_PROBE_ENTRY(ud,ns,name,args)
00070 /**
00071  * User-defined hook probe macro that is invoked after the hook
00072  * has run.
00073  * @param ud A void * user data field that was filled in by the user-
00074  * provided APR_HOOK_PROBE_ENTRY().
00075  * @param ns The namespace prefix of the hook functions
00076  * @param name The name of the hook
00077  * @param rv The return value of the hook, or 0 if the hook is void.
00078  * @param args The argument list to the hook functions, with enclosing
00079  * parens.
00080  */
00081 #define APR_HOOK_PROBE_RETURN(ud,ns,name,rv,args)
00082 /**
00083  * User-defined hook probe macro that is invoked before calling a
00084  * hook function.
00085  * @param ud A void * user data field that was filled in by the user-
00086  * provided APR_HOOK_PROBE_ENTRY().
00087  * @param ns The namespace prefix of the hook functions
00088  * @param name The name of the hook
00089  * @param src The value of apr_hook_debug_current at the time the function
00090  * was hooked (usually the source file implementing the hook function).
00091  * @param args The argument list to the hook functions, with enclosing
00092  * parens.
00093  */
00094 #define APR_HOOK_PROBE_INVOKE(ud,ns,name,src,args)
00095 /**
00096  * User-defined hook probe macro that is invoked after calling a
00097  * hook function.
00098  * @param ud A void * user data field that was filled in by the user-
00099  * provided APR_HOOK_PROBE_ENTRY().
00100  * @param ns The namespace prefix of the hook functions
00101  * @param name The name of the hook
00102  * @param src The value of apr_hook_debug_current at the time the function
00103  * was hooked (usually the source file implementing the hook function).
00104  * @param rv The return value of the hook function, or 0 if the hook is void.
00105  * @param args The argument list to the hook functions, with enclosing
00106  * parens.
00107  */
00108 #define APR_HOOK_PROBE_COMPLETE(ud,ns,name,src,rv,args)
00109 #endif
00110 
00111 /** @} */
00112 
00113 /** macro to return the prototype of the hook function */    
00114 #define APR_IMPLEMENT_HOOK_GET_PROTO(ns,link,name) \
00115 link##_DECLARE(apr_array_header_t *) ns##_hook_get_##name(void)
00116 
00117 /** macro to declare the hook correctly */    
00118 #define APR_DECLARE_EXTERNAL_HOOK(ns,link,ret,name,args) \
00119 typedef ret ns##_HOOK_##name##_t args; \
00120 link##_DECLARE(void) ns##_hook_##name(ns##_HOOK_##name##_t *pf, \
00121                                       const char * const *aszPre, \
00122                                       const char * const *aszSucc, int nOrder); \
00123 link##_DECLARE(ret) ns##_run_##name args; \
00124 APR_IMPLEMENT_HOOK_GET_PROTO(ns,link,name); \
00125 typedef struct ns##_LINK_##name##_t \
00126     { \
00127     ns##_HOOK_##name##_t *pFunc; \
00128     const char *szName; \
00129     const char * const *aszPredecessors; \
00130     const char * const *aszSuccessors; \
00131     int nOrder; \
00132     } ns##_LINK_##name##_t;
00133 
00134 /** macro to declare the hook structure */    
00135 #define APR_HOOK_STRUCT(members) \
00136 static struct { members } _hooks;
00137 
00138 /** macro to link the hook structure */
00139 #define APR_HOOK_LINK(name) \
00140     apr_array_header_t *link_##name;
00141 
00142 /** macro to implement the hook */
00143 #define APR_IMPLEMENT_EXTERNAL_HOOK_BASE(ns,link,name) \
00144 link##_DECLARE(void) ns##_hook_##name(ns##_HOOK_##name##_t *pf,const char * const *aszPre, \
00145                                       const char * const *aszSucc,int nOrder) \
00146     { \
00147     ns##_LINK_##name##_t *pHook; \
00148     if(!_hooks.link_##name) \
00149         { \
00150         _hooks.link_##name=apr_array_make(apr_hook_global_pool,1,sizeof(ns##_LINK_##name##_t)); \
00151         apr_hook_sort_register(#name,&_hooks.link_##name); \
00152         } \
00153     pHook=apr_array_push(_hooks.link_##name); \
00154     pHook->pFunc=pf; \
00155     pHook->aszPredecessors=aszPre; \
00156     pHook->aszSuccessors=aszSucc; \
00157     pHook->nOrder=nOrder; \
00158     pHook->szName=apr_hook_debug_current; \
00159     if(apr_hook_debug_enabled) \
00160         apr_hook_debug_show(#name,aszPre,aszSucc); \
00161     } \
00162     APR_IMPLEMENT_HOOK_GET_PROTO(ns,link,name) \
00163     { \
00164         return _hooks.link_##name; \
00165     }
00166 
00167 /**
00168  * Implement a hook that has no return code, and therefore runs all of the
00169  * registered functions
00170  * @param ns The namespace prefix of the hook functions
00171  * @param link The linkage declaration prefix of the hook
00172  * @param name The name of the hook
00173  * @param args_decl The declaration of the arguments for the hook
00174  * @param args_use The names for the arguments for the hook
00175  * @note The link prefix FOO corresponds to FOO_DECLARE() macros, which
00176  * provide export linkage from the module that IMPLEMENTs the hook, and
00177  * import linkage from external modules that link to the hook's module.
00178  */
00179 #define APR_IMPLEMENT_EXTERNAL_HOOK_VOID(ns,link,name,args_decl,args_use) \
00180 APR_IMPLEMENT_EXTERNAL_HOOK_BASE(ns,link,name) \
00181 link##_DECLARE(void) ns##_run_##name args_decl \
00182     { \
00183     ns##_LINK_##name##_t *pHook; \
00184     int n; \
00185     APR_HOOK_INT_DCL_UD; \
00186 \
00187     APR_HOOK_PROBE_ENTRY(ud, ns, name, args_use); \
00188 \
00189     if(_hooks.link_##name) \
00190         { \
00191         pHook=(ns##_LINK_##name##_t *)_hooks.link_##name->elts; \
00192         for(n=0 ; n < _hooks.link_##name->nelts ; ++n) \
00193             { \
00194             APR_HOOK_PROBE_INVOKE(ud, ns, name, (char *)pHook[n].szName, args_use); \
00195             pHook[n].pFunc args_use; \
00196             APR_HOOK_PROBE_COMPLETE(ud, ns, name, (char *)pHook[n].szName, 0, args_use); \
00197             } \
00198         } \
00199 \
00200     APR_HOOK_PROBE_RETURN(ud, ns, name, 0, args_use); \
00201 \
00202     }
00203 
00204 /* FIXME: note that this returns ok when nothing is run. I suspect it should
00205    really return decline, but that breaks Apache currently - Ben
00206 */
00207 /**
00208  * Implement a hook that runs until one of the functions returns something
00209  * other than OK or DECLINE
00210  * @param ns The namespace prefix of the hook functions
00211  * @param link The linkage declaration prefix of the hook
00212  * @param ret Type to return
00213  * @param name The name of the hook
00214  * @param args_decl The declaration of the arguments for the hook
00215  * @param args_use The names for the arguments for the hook
00216  * @param ok Success value
00217  * @param decline Decline value
00218  * @note The link prefix FOO corresponds to FOO_DECLARE() macros, which
00219  * provide export linkage from the module that IMPLEMENTs the hook, and
00220  * import linkage from external modules that link to the hook's module.
00221  */
00222 #define APR_IMPLEMENT_EXTERNAL_HOOK_RUN_ALL(ns,link,ret,name,args_decl,args_use,ok,decline) \
00223 APR_IMPLEMENT_EXTERNAL_HOOK_BASE(ns,link,name) \
00224 link##_DECLARE(ret) ns##_run_##name args_decl \
00225     { \
00226     ns##_LINK_##name##_t *pHook; \
00227     int n; \
00228     ret rv = ok; \
00229     APR_HOOK_INT_DCL_UD; \
00230 \
00231     APR_HOOK_PROBE_ENTRY(ud, ns, name, args_use); \
00232 \
00233     if(_hooks.link_##name) \
00234         { \
00235         pHook=(ns##_LINK_##name##_t *)_hooks.link_##name->elts; \
00236         for(n=0 ; n < _hooks.link_##name->nelts ; ++n) \
00237             { \
00238             APR_HOOK_PROBE_INVOKE(ud, ns, name, (char *)pHook[n].szName, args_use); \
00239             rv=pHook[n].pFunc args_use; \
00240             APR_HOOK_PROBE_COMPLETE(ud, ns, name, (char *)pHook[n].szName, rv, args_use); \
00241             if(rv != ok && rv != decline) \
00242                 break; \
00243             rv = ok; \
00244             } \
00245         } \
00246 \
00247     APR_HOOK_PROBE_RETURN(ud, ns, name, rv, args_use); \
00248 \
00249     return rv; \
00250     }
00251 
00252 
00253 /**
00254  * Implement a hook that runs until the first function returns something
00255  * other than the value of decline
00256  * @param ns The namespace prefix of the hook functions
00257  * @param link The linkage declaration prefix of the hook
00258  * @param name The name of the hook
00259  * @param ret Type to return
00260  * @param args_decl The declaration of the arguments for the hook
00261  * @param args_use The names for the arguments for the hook
00262  * @param decline Decline value
00263  * @note The link prefix FOO corresponds to FOO_DECLARE() macros, which
00264  * provide export linkage from the module that IMPLEMENTs the hook, and
00265  * import linkage from external modules that link to the hook's module.
00266  */
00267 #define APR_IMPLEMENT_EXTERNAL_HOOK_RUN_FIRST(ns,link,ret,name,args_decl,args_use,decline) \
00268 APR_IMPLEMENT_EXTERNAL_HOOK_BASE(ns,link,name) \
00269 link##_DECLARE(ret) ns##_run_##name args_decl \
00270     { \
00271     ns##_LINK_##name##_t *pHook; \
00272     int n; \
00273     ret rv = decline; \
00274     APR_HOOK_INT_DCL_UD; \
00275 \
00276     APR_HOOK_PROBE_ENTRY(ud, ns, name, args_use); \
00277 \
00278     if(_hooks.link_##name) \
00279         { \
00280         pHook=(ns##_LINK_##name##_t *)_hooks.link_##name->elts; \
00281         for(n=0 ; n < _hooks.link_##name->nelts ; ++n) \
00282             { \
00283             APR_HOOK_PROBE_INVOKE(ud, ns, name, (char *)pHook[n].szName, args_use); \
00284             rv=pHook[n].pFunc args_use; \
00285             APR_HOOK_PROBE_COMPLETE(ud, ns, name, (char *)pHook[n].szName, rv, args_use); \
00286 \
00287             if(rv != decline) \
00288                 break; \
00289             } \
00290         } \
00291 \
00292     APR_HOOK_PROBE_RETURN(ud, ns, name, rv, args_use); \
00293 \
00294     return rv; \
00295     }
00296 
00297     /* Hook orderings */
00298 /** run this hook first, before ANYTHING */
00299 #define APR_HOOK_REALLY_FIRST   (-10)
00300 /** run this hook first */
00301 #define APR_HOOK_FIRST          0
00302 /** run this hook somewhere */
00303 #define APR_HOOK_MIDDLE         10
00304 /** run this hook after every other hook which is defined*/
00305 #define APR_HOOK_LAST           20
00306 /** run this hook last, after EVERYTHING */
00307 #define APR_HOOK_REALLY_LAST    30
00308 
00309 /**
00310  * The global pool used to allocate any memory needed by the hooks.
00311  */ 
00312 APR_DECLARE_DATA extern apr_pool_t *apr_hook_global_pool;
00313 
00314 /**
00315  * A global variable to determine if debugging information about the
00316  * hooks functions should be printed
00317  */ 
00318 APR_DECLARE_DATA extern int apr_hook_debug_enabled;
00319 
00320 /**
00321  * The name of the module that is currently registering a function
00322  */ 
00323 APR_DECLARE_DATA extern const char *apr_hook_debug_current;
00324 
00325 /**
00326  * Register a hook function to be sorted
00327  * @param szHookName The name of the Hook the function is registered for
00328  * @param aHooks The array which stores all of the functions for this hook
00329  */
00330 APR_DECLARE(void) apr_hook_sort_register(const char *szHookName, 
00331                                         apr_array_header_t **aHooks);
00332 /**
00333  * Sort all of the registerd functions for a given hook
00334  */
00335 APR_DECLARE(void) apr_hook_sort_all(void);
00336 
00337 /**
00338  * Print all of the information about the current hook.  This is used for
00339  * debugging purposes.
00340  * @param szName The name of the hook
00341  * @param aszPre All of the functions in the predecessor array
00342  * @param aszSucc All of the functions in the successor array
00343  */
00344 APR_DECLARE(void) apr_hook_debug_show(const char *szName,
00345                                       const char * const *aszPre,
00346                                       const char * const *aszSucc);
00347 
00348 /**
00349  * Remove all currently registered functions.
00350  */
00351 APR_DECLARE(void) apr_hook_deregister_all(void);
00352 
00353 /** @} */
00354 #ifdef __cplusplus
00355 }
00356 #endif
00357 
00358 #endif /* APR_HOOKS_H */
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Defines