From: Justin Seyster <jseyster@cs.sunysb.edu>
Date: Fri, 13 Aug 2010 23:05:32 +0000 (-0400)
Subject: Added documentation for join_on functions.
X-Git-Tag: release-v1.0~72
X-Git-Url: https://git.fsl.cs.stonybrook.edu/?a=commitdiff_plain;h=73c04ed856d08b929d1089e584e7499b347341c7;p=interaspect.git

Added documentation for join_on functions.
---

diff --git a/src/aop-main.c b/src/aop-main.c
index f8b4506..beac841 100644
--- a/src/aop-main.c
+++ b/src/aop-main.c
@@ -76,6 +76,25 @@ regimplify ()
     }
 }
 
+/**
+ * Iterate over the join points in a pointcut.  The join calls the
+ * supplied callback once for each join point, passing the join point
+ * itself and the callback_param value.
+ *
+ * The callback can use capture functions to get information about the
+ * join point and aop_insert_advice() to actually instrument the join
+ * point.
+ *
+ * Join points are only valid for the lifetime of the callback.  When
+ * the callback finishes, the join point is deallocated and any
+ * attempt to access it is an error.
+ *
+ * \param pc The pointcut to iterate over.
+ * \param callback The callback to call for each join point.  The
+ * callback function should have a prototype that matches
+ * #join_callback.
+ * \param callback_param Any data you wish to pass to the callback.
+ */
 void
 aop_join_on (struct aop_pointcut *pc, join_callback callback, 
 	     void *callback_param)
@@ -91,6 +110,26 @@ aop_join_on (struct aop_pointcut *pc, join_callback callback,
   }
 }
 
+/**
+ * Iterate over the join points in a pointcut for a single copy of a
+ * duplicated function.  Calling aop_join_on() without duplicating the
+ * function first will result in an error.  Functions are duplicated
+ * with aop_duplicate().
+ *
+ * This kind of join works just like aop_join_on(), but all join
+ * points are within one copy of the function body.  It is guaranteed
+ * that advice inserted in one copy of a function body will only
+ * execute if that copy is chosen by the distributor, even for
+ * function entry and function exit join points.
+ *
+ * \param pc The pointcut to iterate over.
+ * \param copy The copy to iterate over: zero for the original copy,
+ * non-zero for the new copy.
+ * \param callback The callback to call for each join point.  The
+ * callback function should have a prototype that matches
+ * #join_callback.
+ * \param callback_param Any data you wish to pass to the callback.
+ */
 void
 aop_join_on_copy (struct aop_pointcut *pc, int copy, join_callback callback,
 		  void *callback_param)