Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revisionBoth sides next revision
doc:plans [2014/01/14 10:55] – [with-policy] winklerdoc:plans [2014/01/21 10:32] – [with-policy] winkler
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
     (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 cRight now, just a `timeout-policy` is available that the given `body` stops code after a given amount of time (in seconds) if it hasn't finished by then. 
 + 
 +Use it like this: 
 +```lisp 
 +(with-policy cpl:timeout-policy (5.0) 
 +  (body-code-goes-here)) 
 +``` 
 +And for catching the check condition when the timeout actually happens: 
 +```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))) 
 +```ycle.~%")
                (sleep 2)))))                (sleep 2)))))
 </code> </code>
Line 66: Line 81:
 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-policiescan
     ((my-policy-object (3 1))     ((my-policy-object (3 1))
      (my-policy-object (100 4))      (my-policy-object (100 4))
      (my-other-policy-object ("Test")))      (my-other-policy-object ("Test")))
-  (body-code))+  (body-code))Right now, just a `timeout-policy` is available that the given `body` stops code after a given amount of time (in seconds) if it hasn't finished by then. 
 + 
 +Use it like this: 
 +```lisp 
 +(with-policy cpl:timeout-policy (5.0) 
 +  (body-code-goes-here)) 
 +``` 
 +And for catching the check condition when the timeout actually happens: 
 +```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> </code>
 In this example, the resulting code will be equivalent to the following: In this example, the resulting code will be equivalent to the following:
 <code lisp> <code lisp>
-(with-policy my-policy-object (3 1)+(with-policy my-policy-object (3 1)is available that the given
   (with-policy my-policy-object (100 4)   (with-policy my-policy-object (100 4)
     (with-policy my-other-policy-object ("Test")     (with-policy my-other-policy-object ("Test")
       (body-code))))       (body-code))))
-</code> +</code>```lisp 
-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:can
 <code lisp> <code lisp>
 (with-named-policies (with-named-policies
Line 96: Line 127:
       (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).