Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
Last revisionBoth sides next revision
doc:plans [2014/01/13 10:36] – [with-policy] winklerdoc:plans [2014/12/10 14:50] – bbrieber
Line 21: Line 21:
 <code lisp> <code lisp>
 (define-policy my-policy (max-num match-num) (define-policy my-policy (max-num match-num)
-  (:description "This is an example policy.")+  "This is an example policy."
   (:init (format t "Initializing policy~%")   (:init (format t "Initializing policy~%")
          t)          t)
Line 55: Line 55:
   (with-failure-handling   (with-failure-handling
       ((policy-check-condition-met (f)       ((policy-check-condition-met (f)
-         (declare (ignore f))+         (declare (ignore f))is available that the given
          (do-custom-handling-here)          (do-custom-handling-here)
-         (retry))) ;; Or whatever seems appropriate in your use-case+         (retry))) ;; Or whatever seems appropriate in your use-case e.g. (return)
     (with-named-policy 'my-policy (10 5)     (with-named-policy 'my-policy (10 5)
       (loop do (format t "Main loop cycle.~%")       (loop do (format t "Main loop cycle.~%")
                (sleep 2)))))                (sleep 2)))))
 </code> </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).