summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--sly/signal.scm65
1 files changed, 33 insertions, 32 deletions
diff --git a/sly/signal.scm b/sly/signal.scm
index aede5a1..4f42f75 100644
--- a/sly/signal.scm
+++ b/sly/signal.scm
@@ -95,9 +95,9 @@
(for-each (cut signal-connect! signal <>) inputs)
signal))
-(define (make-signal init)
- "Return a signal box with initial value INIT."
- (make-signal-box (%make-signal init #f '())))
+(define (make-signal value)
+ "Wrap VALUE in a signal."
+ (make-signal-box (%make-signal value #f '())))
(define (make-boxed-signal init proc inputs)
"Return a signal box containing a signal with value INIT, updating
@@ -109,14 +109,13 @@ procedure PROC, and a list of INPUTS."
SIGNAL-BOX-IN changes, the value will be propagated to SIGNAL-OUT."
(hashq-set! (signal-outputs (signal-unbox signal-box-in)) signal-out #f))
-(define (signal-ref signal-box)
- "Return the current value of the signal contained within
-SIGNAL-BOX."
- (%signal-ref (signal-unbox signal-box)))
+(define (signal-ref signal)
+ "Return the value stored within SIGNAL."
+ (%signal-ref (signal-unbox signal)))
(define (signal-ref-maybe object)
- "Retrieves the signal value from OBJECT if it is a signal and or
-simply returns OBJECT otherwise."
+ "Return the value stored within OBJECT if OBJECT is a signal.
+Otherwise, return OBJECT."
(if (signal-box? object)
(signal-ref object)
object))
@@ -134,9 +133,11 @@ all output signals."
(signal-propagate! signal)
*unspecified*)
-(define (signal-set! signal-box value)
- "Change the current value contained within SIGNAL-BOX to VALUE."
- (%signal-set! (signal-unbox signal-box) value))
+(define (signal-set! signal value)
+ "Change the contents of SIGNAL to VALUE. This procedure should
+almost never be used, except to bootstrap a root node of a signal
+graph."
+ (%signal-set! (signal-unbox signal) value))
(define (splice-signals! to from)
"Replace the contents of the signal TO with the contents of the
@@ -209,17 +210,17 @@ run."
(define (signal-merge signal1 signal2 . rest)
"Create a new signal whose value is the that of the most recently
-changed signal in SIGNALs. The initial value is that of the first
-signal in SIGNALS."
- (let ((inputs (append (list signal1 signal2) rest)))
+changed signal in SIGNAL1, SIGNAL2, etc. The initial value is that of
+SIGNAL1."
+ (let ((inputs (cons* signal1 signal2 rest)))
(make-boxed-signal (signal-ref (car inputs))
(lambda (self value)
(%signal-set! self value))
inputs)))
(define (signal-zip . signals)
- "Create a new signal whose value is a list of the values stored in
-the given signals."
+ "Create a new signal whose value is a list of the values stored
+SIGNALS."
(define (current-value)
(map signal-ref signals))
(make-boxed-signal (current-value)
@@ -229,7 +230,7 @@ the given signals."
(define (signal-map proc signal . rest)
"Create a new signal that applies PROC to the values stored in one
-or more SIGNALS."
+or more SIGNALs."
(let ((inputs (cons signal rest)))
(define (current-value)
(apply proc (map signal-ref inputs)))
@@ -240,7 +241,7 @@ or more SIGNALS."
(define (signal-sample-on value-signal sample-signal)
"Create a new signal that takes on the value of VALUE-SIGNAL
-whenever SAMPLE-SIGNAL is updated."
+whenever SAMPLE-SIGNAL receives a new value."
(signal-map (lambda _ (signal-ref value-signal)) sample-signal))
(define (signal-negate signal)
@@ -265,8 +266,8 @@ previously computed value, or INIT for the first call."
(define (signal-filter predicate default signal)
"Create a new signal that keeps an incoming value from SIGNAL when
-it satifies the procedure PREDICATE. The value of the signal is
-DEFAULT when the predicate is never satisfied."
+it satisfies the procedure PREDICATE. The value of the signal is
+DEFAULT in the case that the predicate is never satisfied."
(make-boxed-signal (if (predicate (signal-ref signal))
(signal-ref signal)
default)
@@ -282,8 +283,8 @@ signal is DEFAULT when the predicate is never satisfied."
(signal-filter (lambda (x) (not (predicate x))) default signal))
(define* (signal-drop-repeats signal #:optional (equal? equal?))
- "Create a new signal that filters out new values from SIGNAL that
-are equivalent to the current value. By default, equal? is used for
+ "Create a new signal that drops the value received from SIGNAL when
+it is equivalent to the current value. By default, equal? is used for
testing equivalence."
(signal-drop (let ((prev (signal-ref signal)))
(lambda (current)
@@ -295,17 +296,17 @@ testing equivalence."
(signal-ref signal)
signal))
-(define (signal-switch pred on off)
+(define (signal-switch predicate on off)
"Create a new signal whose value is that of the signal ON when the
signal PRED is true, or the value of the signal OFF otherwise."
(define (current-value)
- (if (signal-ref pred)
+ (if (signal-ref predicate)
(signal-ref on)
(signal-ref off)))
(make-boxed-signal (current-value)
(lambda (self value)
(%signal-set! self (current-value)))
- (list pred)))
+ (list predicate)))
(define (signal-constant constant signal)
"Create a new signal whose value is always CONSTANT no matter the
@@ -337,8 +338,8 @@ of SIGNAL was received."
(signal-map (lambda _ (agenda-time)) signal))
(define (signal-sample step signal)
- "Create a new signal that emits the value contained within SIGNAL
-every STEP ticks of the current agenda."
+ "Create a new signal that takes on the value of SIGNAL every STEP
+ticks."
;; To prevent memory leaks, the new signal is stored within a weak
;; value hash table and never bound to a variable within the main
;; body of the procedure. When this signal is GC'd, the sampling
@@ -366,15 +367,15 @@ every STEP ticks of the current agenda."
(signal-sample step (make-signal step)))
(define (signal-since step signal)
- "Create a new signal that emits the time since the last value was
-received from SIGNAL in STEP increments."
+ "Create a new signal that emits the time since SIGNAL was updated
+every STEP ticks."
(signal-map (lambda (time)
(- (agenda-time) time))
(signal-sample step (signal-time signal))))
(define (signal-delay delay signal)
"Create a new signal that delays propagation of SIGNAL by DELAY
-ticks of the current agenda."
+ticks."
(make-boxed-signal (signal-ref signal)
(lambda (self value)
(schedule
@@ -385,7 +386,7 @@ ticks of the current agenda."
(define (signal-throttle delay signal)
"Return a new signal that propagates SIGNAL at most once every DELAY
-ticks of the current agenda."
+ticks."
(make-boxed-signal (signal-ref signal)
(let ((last-time (agenda-time)))
(lambda (self value)