moar docstrings

[8sync.git] / loopy.scm

diff --git a/loopy.scm b/loopy.scm
index cc1ee7889bcfdcb1a253b0ec0049c84a3a730890..1c26a2f3b211a31d48c4746e70edd6901c31b4de 100644 (file)
--- a/loopy.scm
+++ b/loopy.scm
@@ -87,6 +87,8 @@
                       (except-port-map (make-hash-table))
                       (schedule (make-schedule))
                       (time (gettimeofday)))
+  ;; TODO: document arguments
+  "Make a fresh agenda."
   (make-agenda-intern queue prompt
                       read-port-map write-port-map except-port-map
                       schedule time))
@@ -158,12 +160,12 @@ run (time-segment-right-format) first."
   (sec time-delta-sec)
   (usec time-delta-usec))
 
-(define* (make-time-delta sec #:optional usec)
+(define* (make-time-delta sec #:optional (usec 0))
   "Make a <time-delta> of SEC seconds and USEC microseconds.
 
 This is used primarily so the agenda can recognize RUN-REQUEST objects
 which are meant "
-  (make-time-delta-intern sec (or usec 0)))
+  (make-time-delta-intern sec usec))
 
 (define tdelta make-time-delta)
 
@@ -183,16 +185,19 @@ Will produce (0 . 0) instead of a negative number, if needed."
         (else time)))
 
 (define (time-delta+ time time-delta)
+  "Increment a TIME by the value of TIME-DELTA"
   (time-carry-correct
    (cons (+ (car time) (time-delta-sec time-delta))
          (+ (cdr time) (time-delta-usec time-delta)))))
 
 (define (time-minus time1 time2)
+  "Subtract TIME2 from TIME1"
   (time-carry-correct
    (cons (- (car time1) (car time2))
          (- (cdr time2) (cdr time2)))))
 
 (define (time-plus time1 time2)
+  "Add TIME1 and TIME2"
   (time-carry-correct
    (cons (+ (car time1) (car time2))
          (+ (cdr time2) (cdr time2)))))
@@ -204,6 +209,7 @@ Will produce (0 . 0) instead of a negative number, if needed."
   (segments schedule-segments set-schedule-segments!))
 
 (define* (make-schedule #:optional segments)
+  "Make a schedule, optionally pre-composed of SEGMENTS"
   (make-schedule-intern (or segments '())))
 
 (define (schedule-soonest-time schedule)
@@ -218,6 +224,7 @@ Will produce (0 . 0) instead of a negative number, if needed."
 ;;   but at least it'll be reasonably easy to refactor to
 ;;   a more functional setup?
 (define (schedule-add! schedule time proc)
+  "Mutate SCHEDULE, adding PROC at an appropriate time segment for TIME"
   (let ((time (time-segment-right-format time)))
     (define (new-time-segment)
       (let ((new-segment
@@ -255,6 +262,7 @@ Will produce (0 . 0) instead of a negative number, if needed."
      (loop (schedule-segments schedule)))))
 
 (define (schedule-empty? schedule)
+  "Check if the SCHEDULE is currently empty"
   (eq? (schedule-segments schedule) '()))
 
 (define (schedule-segments-split schedule time)
@@ -301,36 +309,6 @@ Will produce (0 . 0) instead of a negative number, if needed."
    segments))
 
 
-\f
-;;; Port handling
-;;; =============
-
-(define (make-port-mapping)
-  (make-hash-table))
-
-(define* (port-mapping-set! port-mapping port #:optional read write except)
-  "Sets port-mapping for reader / writer / exception handlers"
-  (if (not (or read write except))
-      (throw 'no-handlers-given "No handlers given for port" port))
-  (hashq-set! port-mapping port
-              `#(,read ,write ,except)))
-
-(define (port-mapping-remove! port-mapping port)
-  (hashq-remove! port-mapping port))
-
-;; TODO: This is O(n), I'm pretty sure :\
-;; ... it might be worthwhile for us to have a
-;;   port-mapping record that keeps a count of how many
-;;   handlers (maybe via a promise?)
-(define (port-mapping-empty? port-mapping)
-  "Is this port mapping empty?"
-  (eq? (hash-count (const #t) port-mapping) 0))
-
-(define (port-mapping-non-empty? port-mapping)
-  "Whether this port-mapping contains any elements"
-  (not (port-mapping-empty? port-mapping)))
-
-
 \f
 ;;; Request to run stuff
 ;;; ====================
@@ -375,6 +353,7 @@ Will produce (0 . 0) instead of a negative number, if needed."
 (define %current-agenda (make-parameter #f))
 
 (define (update-agenda-from-select! agenda)
+  "Potentially (select) on ports specified in agenda, adding items to queue"
   (define (hash-keys hash)
     (hash-map->list (lambda (k v) k) hash))
   (define (get-wait-time)
@@ -453,6 +432,8 @@ Will produce (0 . 0) instead of a negative number, if needed."
                        #:key stop-condition
                        (get-time gettimeofday)
                        (handle-ports update-agenda-from-select!))
+  ;; TODO: Document fields
+  "Start up the AGENDA"
   (let loop ((agenda agenda))
     (let ((agenda   
            ;; @@: Hm, maybe here would be a great place to handle