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/14 10:55] – [with-policy] winklerdoc:plans [2014/12/10 14:50] – bbrieber
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.~%")
Line 66: Line 66:
 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 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 ''my-other-policy-object'' takes a string as an argument.+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> <code lisp>
 (with-policies (with-policies
Line 81: Line 81:
       (body-code))))       (body-code))))
 </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: 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> <code lisp>
Line 89: Line 90:
   (body-code))   (body-code))
 </code> </code>
-This results in:+This results in the same behavior as:
 <code lisp> <code lisp>
 (with-named-policy 'my-policy (3 1) (with-named-policy 'my-policy (3 1)
Line 96: Line 97:
       (body-code))))       (body-code))))
 </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).