From ffb9104fcc3ad3938705ce99902b02b2cee72566 Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Wed, 8 Jul 2015 23:08:14 -0700 Subject: [PATCH] Explain how signals start work upon instantiation --- Documentation/DesignGuidelines.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/Documentation/DesignGuidelines.md b/Documentation/DesignGuidelines.md index 6b866510..e563eb3d 100644 --- a/Documentation/DesignGuidelines.md +++ b/Documentation/DesignGuidelines.md @@ -133,7 +133,14 @@ handler finishes. ## The `Signal` contract +**TODO** + #### Signals start work when instantiated + +When a `Signal` is created, it immediately executes the generator closure that +was passed to the initializer. This means that instantiating a `Signal` may have +side effects, or start work even before the initializer returns. + #### Observing a signal does not have side effects #### All observers of a signal see the same events at the same time #### Signals are retained until a terminating event occurs @@ -141,6 +148,8 @@ handler finishes. ## The `SignalProducer` contract +**TODO** + #### Signal producers start work on demand by creating signals #### Each produced signal may send different events at different times #### Signal operators can be lifted to apply to signal producers @@ -148,6 +157,8 @@ handler finishes. ## Best practices +**TODO** + #### Indent signal and producer chains consistently #### Process only as many values as needed @@ -170,6 +181,8 @@ sooner, potentially saving a significant amount of work. ## Implementing new operators +**TODO** + #### Prefer writing operators that apply to both signals and producers #### Compose existing operators when possible #### Forward error and interruption events