Differences

This shows you the differences between two versions of the page.

--- doc:plans [2014/01/13 10:07] – [with-policy] winkler
+++ doc:plans [2014/12/10 14:50] – bbrieber
@@ Line 21: / Line 21: @@
 <code lisp>
 (define-policy my-policy (max-num match-num)
-  (:description "This is an example policy.")
+  "This is an example policy."
   (:init (format t "Initializing policy~%")
          t)
@@ Line 43: / Line 43: @@
              (sleep 2))))
 </code>
+=== Exception handling ===
+When policies are used, multiple failures can be signalled. The most meaningful of those are
+  * ''policy-not-found'': Signalled when a named policy is used that was not defined before.
+  * ''policy-init-failed'': Signalled when initialization of a policy went wrong (i.e. '':init'' returned ''nil'').
+  * ''policy-check-condition-met'': The '':check'' condition of the policy returned a non-''nil'' value, '':recover'' was executed and the ''body'' code was interrupted before it could complete execution.
+If one wants to monitor the triggering of a policy's '':check'' condition, this can be achieved like this:
+<code lisp>
+(top-level
+  (with-failure-handling
+      ((policy-check-condition-met (f)
+         (declare (ignore f))is available that the given
+         (do-custom-handling-here)
+         (retry))) ;; Or whatever seems appropriate in your use-case e.g. (return)
+    (with-named-policy 'my-policy (10 5)
+      (loop do (format t "Main loop cycle.~%")
+               (sleep 2)))))
+</code>
+=== Using multiple policies at once ===
+When multiple policies are to be used (either a mix of different policies, or the same policy multiple times, each with different parameters), two helpful macros can be used: ''with-policies'' and ''with-named-policies''. Both of these take lists of policies, together with their respective instantiation parameters, as arguments.
+When policy instances by the names ''my-policy-object'' and ''my-other-policy-object'' should be used, the following code snippet reflects this behaviour. The policy ''my-policy-object'' takes two ''int''s as parameters, while ''is available that the givenmy-other-policy-object'' takes a string as an argument.
+<code lisp>
+(with-policies
+    ((my-policy-object (3 1))
+     (my-policy-object (100 4))
+     (my-other-policy-object ("Test")))
+  (body-code))
+</code>
+In this example, the resulting code will be equivalent to the following:
+<code lisp>
+(with-policy my-policy-object (3 1)
+  (with-policy my-policy-object (100 4)
+    (with-policy my-other-policy-object ("Test")
+      (body-code))))
+</code>
+The same princple applies to ''with-named-policies'', with the only difference being that it does not take policy instances, but policy name symbols as parameters:
+<code lisp>
+(with-named-policies
+    (('my-policy (3 1))
+     ('my-policy (100 4))
+     ('my-other-policy ("Test")))
+  (body-code))
+</code>
+This results in the same behavior as:
+<code lisp>
+(with-named-policy 'my-policy (3 1)
+  (with-named-policy 'my-policy (100 4)
+    (with-named-policy 'my-other-policy ("Test")
+      (body-code))))
+</code>
+=== Built-in Policies ===
+== timeout-policy ==
+When a piece of code only has a limited maximum amount of time for execution (and must be aborted after that duration), the ''timeout-policy'' comes in handy.
+Use it like this:
+<code lisp>
+(with-policy cpl:timeout-policy (5.0) ; Timeout after 5.0 seconds (fractions may be used)
+  (body-code-goes-here))
+</code>
+And for catching the check condition when the timeout actually happens:
+<code lisp>
+(with-failure-handling
+    ((policy-check-condition-met (f)
+      (declare (ignore f))
+      (handle-error-here-and-maybe-retry)))
+  (with-policy cpl:timeout-policy (5.0)
+    (body-code-goes-here)))
+</code>
+The ''timeout-policy'' stops the given ''body'' code after a given amount of time (in seconds) if it hasn't finished by then. This helps to add a ''timeout'' functionality to functions that do not inherently support a timeout mechanism (blocking function calls).