Further updates to support call_counters

git-svn-id: https://yap.svn.sf.net/svnroot/yap/trunk@581 b08c6af1-5177-4d33-ba66-4b1c6b8b522a

docs/yap.tex

@@ -155,7 +155,7 @@ Built In Predicates
 * OS:: Access to Operating System Functionality
 * Term Modification:: Updating Prolog Terms
 * Profiling:: Profiling Prolog Execution
-* Calls Execution Limits:: Limiting the Maximum Number of Reductions
+* Call Counting:: Limiting the Maximum Number of Reductions
 * Arrays:: Supporting Global and Local Arrays
 * Preds:: Information on Predicates
 * Misc:: Miscellaneous Predicates
@@ -2035,7 +2035,7 @@ Builtins, Debugging, Syntax, Top
 * OS:: Access to Operating System Functionality
 * Term Modification:: Updating Prolog Terms
 * Profiling:: Profiling Prolog Execution
-* Calls Execution Limits:: Limiting the Maximum Number of Reductions
+* Call Counting:: Limiting the Maximum Number of Reductions
 * Arrays:: Supporting Global and Local Arrays
 * Preds:: Information on Predicates
 * Misc:: Miscellaneous Predicates
@@ -5744,6 +5744,10 @@ retries.
 These counters can be used to find out how many calls a certain
 goal takes to execute. They can also be used as timers.
 
+The code for the call counters piggybacks on the profiling
+code. Therefore, activating the call counters also activates the call
+counters.
+
 These are  the predicates that access and manipulate the call counters:
 
 @table @code
@@ -5778,7 +5782,29 @@ counter @code{retries} reaches 0;
 reaches 0.
 @end itemize
 
+Next, we show a simple example of how to use call counters:
+@example
+G(X,Y,Z,I,J) :-
+        array_element(X,I,E1),
+        array_element(Y,J,E2),  
+        array_element(Z,I,E3),  
+        E1 is E2+E3.
+@end example
+   ?- yap_flag(call_counting,on), [-user]. l :- l. end_of_file. yap_flag(call_counting,off).
+
+yes
+
+yes
+   ?- catch((call_count(10000,_,_),l),call_counter,format("limit_exceeded.~n",[])).
+
+limit_exceeded.
+
+yes
 @end table
+Notice that we first compile the looping predicate @code{l/0} with
+@code{call_counting} @code{on}. Next, we @code{catch/3} to handle an
+exception when @code{l/0} performs more than 10000 reductions.
+
 
 @node Arrays, Preds, Profiling , Top
 @section Arrays