From: Justin Seyster Date: Tue, 21 Sep 2010 02:05:31 +0000 (-0400) Subject: Added a more useful introduction in the main documentation page. X-Git-Tag: release-v1.0~28^2~21 X-Git-Url: https://git.fsl.cs.sunysb.edu/?a=commitdiff_plain;h=e34f36d26017094891ce63c2aca353ed787cdc54;p=interaspect.git Added a more useful introduction in the main documentation page. Also documented aop_joinpoint and aop_dynval. --- diff --git a/src/aop-doxy-main.c b/src/aop-doxy-main.c index 6428f70..cf83099 100644 --- a/src/aop-doxy-main.c +++ b/src/aop-doxy-main.c @@ -14,16 +14,131 @@ #error This file serves only as documentation. Do not compile it. -/** - * \defgroup assign_pc Assignment Pointcut Functions - */ - /** \mainpage The InterAspect Framework + * + * \section intro Introduction + * InterAspect provides a simple framework for writing GCC plug-ins + * that provide instrumentation. Instrumentation consists of + * advice function calls that can be inserted at various + * program point. For example, it is possible to insert an advice + * call at every call to malloc, passing the allocated + * size and the address of the allocated region to the advice + * function. + * + * Though plug-ins built with the InterAspect framework run in GCC, + * they depend only on InterAspect files. An InterAspect-based + * plug-in just needs to include the main InterAspect header file, + * aop.h, and link with the InterAspect static library. + * + * All InterAspect functions begin with the aop_ prefix. * * \section pc Pointcuts - * InterAspect defines four types of pointcuts. + * An InterAspect-based plug-in finds program points in the target + * program by construction a pointcut, which is a set of points + * in the program available for instrumentation. These program points + * are called join points. + * + * There are four types of pointcuts available in InterAspect, which + * can each be constructed using a match function. Match functions + * have the prefix aop_match_. + * * - \ref entry_pc "Function entry" pointcuts. * - \ref exit_pc "Function exit" pointcuts. * - \ref call_pc "Function call" pointcuts. * - \ref assign_pc "Assignment" pointcuts. + * + * After construction a pointcut, it is possible to refine the set + * using filter functions, which have the prefix + * aop_filter_. For example, it is possible to define a + * pointcut that only matches calls to malloc using + * aop_filter_call_pc_by_name(). + * + * \section join_on Join operations + * Plug-ins iterate over the join points in a pointcut using a \ref + * join "join operation". The plug-in provides a callback to the join + * which gets called once for each join point. + * + * The callback can use capture functions (with an + * aop_capture_ prefix) to get information about the join + * point. Some capture functions return an aop_dynval, which + * represents a value that will not be known until the join point + * executes. + * + * The callback can also insert an advice call using + * aop_insert_advice(). It is possible to pass arbitrary parameters + * to an advice function, including dynval values. + * + * \section setup Setting it up + * Creating and joining on pointcuts are operations that occur within + * a pass. In GCC, a pass is a function that executes once for + * each compiled function, transforming the compiled function in some + * way. InterAspect passes transform compiled functions by adding + * instrumentation. + * + * A plug-in adds one or more passes by calling aop_register_pass() + * from its main function, which must be named aop_main. + * + * \section memory Memory management + * + * InterAspect functions return various data structures that are + * dynamically allocated, but you are not responsible for managing or + * freeing any of them. InterAspect uses GCC's internal garbage + * collector to free all of its data. + * + * Beware, however, that once a data structure's lifetime is over, + * that structure may be deallocated while your plug-in still holds a + * pointer to it. Attempting to use one of these pointers will have + * undefined results. Make sure not to hold a reference to an object + * past its lifetime. The lifetime for each struct is listed in its + * documentation. + */ + +/** + * \struct aop_dynval + * \brief Representation of a runtime value. + * + * An aop_dynval serves as a placeholder during compile time for a + * value that will not be known until runtime. An aop_dynval gets + * returned by a capture function, such as aop_capture_return_value(), + * and can be passed to an advice function inserted with + * aop_insert_advice(). + * + * Internally, every aop_dynval has its own type, which is determined + * by how it was captured. For example, an aop_dynval created with + * aop_capture_return_value() will have its type set based on how the + * corresponding pointcut was filtered using + * aop_filter_call_pc_by_return_type(). (It is an error to capture + * the return value of a function call when the corresponding pointcut + * was not filtered by type. You must use + * aop_capture_return_value_by_type() instead.) + * + * At runtime, the advice function itself simply gets the captured + * value; it will never see the original aop_dynval object. + * + * Use the #AOP_DYNVAL macro when passing an aop_dynval to + * aop_insert_advice(). + * + * All aop_dynval objects are only valid while the aop_joinpoint used + * to create them remains valid. Because an aop_dynval represents a + * value captured from a join point, all capture functions that return + * an aop_dynval take an aop_joinpoint as a parameter. When the + * aop_joinpoint becomes invalid (when the current callback finishes), + * these aop_dynval objects also become invalid. See the + * aop_joinpoint documentation for more information. + */ + +/** + * \struct aop_joinpoint + * \brief A single program point that is available for + * instrumentation. + * + * The only way to obtain a join point is by joining on an + * aop_pointcut using a \ref join "join function". Each join point + * will be passed to the specified callback function. + * + * A join point is only valid during the callback's execution. Once + * the callback finishes, the aop_joinpoint is deallocated. You + * should never store a pointer to an aop_joinpoint in any global data + * structure, in order to avoid any accesses to the join point after + * it becomes invalid. */ diff --git a/src/aop-main.c b/src/aop-main.c index 89210f8..ccd488e 100644 --- a/src/aop-main.c +++ b/src/aop-main.c @@ -102,6 +102,7 @@ regimplify () * callback function should have a prototype that matches * #join_callback. * \param callback_param Any data you wish to pass to the callback. + * \ingroup join */ void aop_join_on (struct aop_pointcut *pc, join_callback callback, @@ -137,6 +138,7 @@ aop_join_on (struct aop_pointcut *pc, join_callback callback, * callback function should have a prototype that matches * #join_callback. * \param callback_param Any data you wish to pass to the callback. + * \ingroup join */ void aop_join_on_copy (struct aop_pointcut *pc, int copy, join_callback callback, diff --git a/src/aop.h b/src/aop.h index fb322dc..5cbdb6c 100644 --- a/src/aop.h +++ b/src/aop.h @@ -99,11 +99,16 @@ struct aop_type; */ typedef unsigned int (*pass_callback) (); +/** + * \defgroup join Join Functions + */ + /** * \brief Type for aop_join_on() callbacks. * * The function type for callback functions to be used for iterating * over a pointcut with aop_join_on(). + * \ingroup join */ typedef void (*join_callback) (struct aop_joinpoint *, void *callback_param);