Differences
This shows you the differences between two versions of the page.
Next revision | Previous revision | ||
doc:plans [2014/01/13 06:52] – created gkazhoya | doc:plans [2015/05/11 17:06] (current) – gkazhoya | ||
---|---|---|---|
Line 1: | Line 1: | ||
+ | //**Note:** this page is deprecated. Please use [[tutorials: | ||
+ | |||
====== Writing Plans ====== | ====== Writing Plans ====== | ||
==== with-policy ==== | ==== with-policy ==== | ||
+ | {{ : | ||
+ | |||
+ | Policies can be used to define generic monitoring behavior that should run concurrently besides main functionality code. Such a policy might be monitoring | ||
+ | * the position of an object inside a robot gripper to see whether it is moving out of the gripper (losing the object) | ||
+ | * the position of an object in the real world, in order to keep the robot' | ||
+ | * the collision of a robot joint with objects in the real world | ||
+ | * generic events that must definitely interrupt a certain piece of code, but are too specialized to be implemented directly in the monitored code itself | ||
+ | |||
+ | A policy consists of multiple parts: | ||
+ | * A name (to identify it) | ||
+ | * A description string (to make its purpose clear) | ||
+ | * A parameter list (which can be used to specialize a generic policy for a situation at hand, without generating a new policy every time the situation changes slightly) | ||
+ | * Code blocks that need to be evaluated during monitoring | ||
+ | |||
+ | === Usage example === | ||
+ | An example of how to define a policy is shown here. The policy accepts two custom parameters, one defining a maximum number and one a match number. During execution of the main '' | ||
<code lisp> | <code lisp> | ||
(define-policy my-policy (max-num match-num) | (define-policy my-policy (max-num match-num) | ||
+ | "This is an example policy." | ||
+ | (:init (format t " | ||
+ | t) | ||
(:check (format t " | (:check (format t " | ||
- | | + | to ~a equals ~a~%" max-num match-num) |
(let ((rnd (random max-num))) | (let ((rnd (random max-num))) | ||
(format t "Got number ~a~%" rnd) | (format t "Got number ~a~%" rnd) | ||
Line 17: | Line 38: | ||
</ | </ | ||
+ | The calling code for using the policy uses '' | ||
<code lisp> | <code lisp> | ||
(top-level | (top-level | ||
Line 23: | Line 45: | ||
| | ||
</ | </ | ||
+ | |||
+ | === Exception handling === | ||
+ | When policies are used, multiple failures can be signalled. The most meaningful of those are | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | |||
+ | If one wants to monitor the triggering of a policy' | ||
+ | <code lisp> | ||
+ | (top-level | ||
+ | (with-failure-handling | ||
+ | ((policy-check-condition-met (f) | ||
+ | | ||
+ | | ||
+ | | ||
+ | (with-named-policy ' | ||
+ | (loop do (format t "Main loop cycle.~%" | ||
+ | | ||
+ | </ | ||
+ | |||
+ | === 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), | ||
+ | |||
+ | When policy instances by the names '' | ||
+ | <code lisp> | ||
+ | (with-policies | ||
+ | ((my-policy-object (3 1)) | ||
+ | | ||
+ | | ||
+ | (body-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 (" | ||
+ | (body-code)))) | ||
+ | </ | ||
+ | |||
+ | The same princple applies to '' | ||
+ | <code lisp> | ||
+ | (with-named-policies | ||
+ | ((' | ||
+ | | ||
+ | | ||
+ | (body-code)) | ||
+ | </ | ||
+ | This results in the same behavior as: | ||
+ | <code lisp> | ||
+ | (with-named-policy ' | ||
+ | (with-named-policy ' | ||
+ | (with-named-policy ' | ||
+ | (body-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 '' | ||
+ | |||
+ | Use it like this: | ||
+ | <code lisp> | ||
+ | (with-policy cpl: | ||
+ | (body-code-goes-here)) | ||
+ | </ | ||
+ | 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: | ||
+ | (body-code-goes-here))) | ||
+ | </ | ||
+ | The '' |