((section 2 "Outdated egg!" (p "This is an egg for CHICKEN 4, the unsupported old release.  You're almost certainly looking for " (int-link "/eggref/5/pigeon-hole" "the CHICKEN 5 version of this egg") ", if it exists.") (p "If it does not exist, there may be equivalent functionality provided by another egg; have a look at the " (link "https://wiki.call-cc.org/chicken-projects/egg-index-5.html" "egg index") ". Otherwise, please consider porting this egg to the current version of CHICKEN.")) (section 2 "pigeon-hole" (p "A mailbox constrained by capacity.") (ul (li "API similar to mailbox.") (li "No timeouts we love our pigeons too much.") (li "Flow control.  " (tt "send/blocking!") " blocks if capacity is exceeded.")) (p "A second module " (int-link "pigeonry") " - currently unstable in API and undocumented - provides a threadpool.  This is only slightly faster than creating a fresh thread, catching exceptions and run job it does while still obeying the capacity limit. This module " (tt "NYD") " (not yet documented) at all.")) (section 2 "API" (def (sig (procedure "(isa? *) -> boolean" (id isa?))) (p "Test predicate for " (tt "PIGEON-HOLE") ".")) (def (sig (procedure "(: make (&optional NAME #!key (capacity: 0) -> {{PIGEON-HOLE}}))" (id :))) (p "Return a " (tt "PIGEON-HOLE") " constrained by capacity.")) (def (sig (procedure "(size PIGEON-HOLE) -> fixnum" (id size))) (p "Return number of pigeons in " (tt "PIGEON-HOLE") ".")) (def (sig (procedure "(empty? PIGEON-HOLE) -> boolean" (id empty?))) (p "Test " (tt "PIGEON-HOLE") " to be empty.")) (def (sig (procedure "(count PIGEON-HOLE) -> fixnum" (id count))) (p "Return number of waiters on " (tt "PIGEON-HOLE") ".")) (def (sig (procedure "(send! PIGEON-HOLE VALUE) -> boolean" (id send!))) (p "Immediately send " (tt "VALUE") " to " (tt "PIGEON-HOLE") ".  Does *not* respect capacity limits!")) (def (sig (procedure "(send/blocking! PIGEON-HOLE VALUE [BLOCK]) -> boolean" (id send/blocking!))) (p "Send " (tt "VALUE") " to " (tt "PIGEON-HOLE") ", blocks if capacity is reached.") (p (tt "BLOCK") " is either a boolean or a procedure taking the queue as argument and returning a boolean.  If it is a procedure it is call in tail position when the call would block.  If " (tt "#f") " does not block but return #f.  Default if " (tt "#t") ": block for capacity.") (p "Return: " (tt "#t") " if value was send.")) (def (sig (procedure "(receive! PIGEON-HOLE) -> *" (id receive!))) (p "Receive value from " (tt "PIGEON-HOLE") ", block if none available.")) (section 3 "Unstable API" (def (sig (procedure "(send-list/anyway!! PIGEON-HOLE LIST [NUM LAST]) -> undefined" (id send-list/anyway!!))) (p "Append all values from " (tt "LIST") " to " (tt "PIGEON-HOLE") ".") (p "It is an error to access " (tt "LIST") " after this call.  Optional " (tt "NUM") " and " (tt "LAST") " may be given for optimization.  Must be the length of the " (tt "LIST") " and the last pair of it.  All bets are off otherwise.")) (def (sig (procedure "(receive-all! PIGEON-HOLE) -> LIST" (id receive-all!))) (p "Receive list of all currently available values from " (tt "PIGEON-HOLE") ".")))) (section 2 "Examples" (pre "   (module\n    test\n    (test-run)\n    (import scheme chicken srfi-18 extras)\n    (import (prefix pigeon-hole mailbox-))\n   (define mb (mailbox-make 'm0 capacity: 10))\n   ;;\n   ;;(define active-mailbox-send! mailbox-send!)\n   (define active-mailbox-send! mailbox-send/blocking!)\n   ;;\n   (cond-expand\n    (compiling\n     (define turns 1000000))\n    (else\n     (define turns 1000)))\n   ;;\n   (define tw\n     (make-thread\n      (lambda ()\n (do ((i 0 (add1 i)))\n     ((= i turns))\n   (active-mailbox-send! mb i)))\n      'w))\n   ;;\n   (define tr\n     (make-thread\n      (lambda ()\n (do ((i 0 (add1 i)))\n     ((= i turns))\n   (mailbox-receive! mb)\n   ))\n      'r))\n   ;;\n   (define (test-run)\n     (thread-start! tr)\n     (define t0 (current-milliseconds))\n     (thread-start! tw)\n     (thread-join! tr)\n     (define t1 (current-milliseconds))\n     (format #t \"~a message passings in ~a (~a per ms)\\n \"\n             turns (- t1 t0) (/ turns (- t1 t0)))\n     )\n   ) (import test) (test-run)")) (section 2 "About this egg" (section 3 "Source code" (p "Maintained at github " (link "https://github.com/0-8-15/pigeon-hole" "pigeon-hole") ".")) (section 3 "Author" (p "Jörg F. Wittenberger")) (section 3 "License" (p "BSD"))))