((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/async-io" "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.") (toc)) (section 2 "async-io" (p "Asynchronous I/O Library for Chicken Scheme.") (section 3 "Repository" (p (link "https://github.com/yarnoiser/async-io" "https://github.com/yarnoiser/async-io"))) (section 3 "Usage" (highlight scheme "(use async-io)") (section 4 "Readers" (p "Readers are used to read strings from a file descriptor asynchronously and return tokens identified by a separator procedure.") (section 5 "make-reader" (def (sig (procedure "(make-reader fd sep-proc)" (id make-reader))) (p "Sets the file descriptor " (i "fd") " to non-blocking mode. Returns a reader which is used to read input from the file descriptor " (i "fd") ". This reader separates tokens using " (i "sep-proc") "."))) (section 5 "reader?" (def (sig (procedure " (reader? x) " (id reader?))) (p "Returns true if " (i "x") " is a reader object, otherwise returns false."))) (section 5 "reader-fd" (def (sig (procedure " (reader-fd x) " (id reader-fd))) (p "Returns the file descriptor belonging to reader " (i "x") "."))) (section 5 "reader-ready?" (def (sig (procedure " (reader-ready? x) " (id reader-ready?))) (p "Returns true if there is input waiting to be read by the reader " (i "x") "."))) (section 5 "thread-wait-for-reader!" (def (sig (procedure " (thread-wait-for-reader! x) " (id thread-wait-for-reader!))) (p "Suspends the current thread until the file descriptor belonging to reader " (i "x") " is ready to be read. Equivalent to:") (highlight scheme "(thread-wait-for-i/o! (reader-fd x))"))) (section 5 "reader-read!" (def (sig (procedure " (reader-read! x) " (id reader-read!))) (p "Reads input from the file descriptor belonging to reader " (i "x") ". Performs separation on any input read. Throws an exception if there is no input to be read by the reader."))) (section 5 "reader-has-token?" (def (sig (procedure " (reader-has-token? x) " (id reader-has-token?))) (p "Returns true if the reader " (i "x") " has a complete token from it's input stream. Otherwise returns false."))) (section 5 "reader-get-token!" (def (sig (procedure " (reader-get-token! x) " (id reader-get-token!))) (p "If reader " (i "x") " found a token using it's separator procedure during the last call to (reader-read! x), then that token will be returned as a string. Otherwise an empty string is returned."))) (section 5 "Example" (p "Echo the first scheme expression from stdin.") (highlight scheme "(define reader (make-reader fileno/stdin sep-scheme-expr))\n\n(let loop ()\n  (cond\n    ((reader-has-token? reader)\n     (print (reader-get-token! reader)))\n    ((reader-ready? reader)\n     (begin (reader-read! reader)\n            (loop)))\n    (else\n     (loop))))"))) (section 4 "Separator Procedures" (p "Separator procedures are used by readers to identify tokens to be returned with " (i "reader-get-token!") ". These procedures take a string to separate as an argument and return two values: a token separated from the main string, and the remainder of the string after the token. Token separation is done with every call to reader-read! before input is placed within a reader's buffer. This egg comes with two pre-made separator procedure: sep-scheme-expr and sep-line.")) (section 4 "Example" (p "The following separator procedure separates tokens delimited by commas.") (highlight scheme "(use srfi-13)\n\n(define (sep-comma str)\n  (let ((len (string-length str)))\n    (let loop ((i 0))\n      (cond\n        ((= i len)\n         (values \"\" str))\n        ((eqv? (string-ref str i) #\\,)\n         (values (string-take str (add1 i)) (string-drop str (add1 i))))\n        (else\n         (loop (add1 i)))))))") (section 5 "sep-scheme-expr" (def (sig (procedure " (sep-scheme-expr str) " (id sep-scheme-expr))) (p "A separator procedure for scheme expressions (without chicken extensions). Returns two values: The first value returned is the first complete scheme expression found in " (i "str") " or an empty string if no scheme expressions were found. The second value returned is the remainder of the " (i "str") " after the first complete scheme expression, or an empty string if there is no content after the first expression."))) (section 5 "sep-line" (def (sig (procedure " (sep-line str) " (id sep-line))) (p "A separator procedure for lines. Returns two values: The first value returned is the first line found in " (i "str") ", including the newline character. The second value returned is the remainder of " (i "str") " after the first line, or an empty string if " (i "str") " only contained one line.")))) (section 4 "Writers" (p "Writers are used to asynchronously write strings to a file descriptor.") (section 5 "make-writer" (def (sig (procedure " (make-writer fd) " (id make-writer))) (p "Sets the file descriptor " (i "fd") " into non-blocking mode and returns a writer which is used to read input from " (i "fd") "."))) (section 5 "writer?" (def (sig (procedure " (writer? x) " (id writer?))) (p "Returns true if " (i "x") " is a writer. Otherwise returns false."))) (section 5 "writer-fd" (def (sig (procedure " (writer-fd x) " (id writer-fd))) (p "Returns the file descriptor belonging to the writer " (i "x") "."))) (section 5 "writer-ready?" (def (sig (procedure " (writer-ready? x) " (id writer-ready?))) (p "Returns true if the file descriptor belonging to writer " (i "x") " is ready to be written to. Otherwise returns false."))) (section 5 "thread-wait-for-writer!" (def (sig (procedure " (thread-wait-for-writer! x) " (id thread-wait-for-writer!))) (p "Suspends the current thread until the file descriptor belonging to writer " (i "x") " is ready to be written to. Equivalent to:") (highlight scheme "(thread-wait-for-i/o! (writer-fd x))"))) (section 5 "writer-enqueue!" (def (sig (procedure " (writer-enqueue! x str) " (id writer-enqueue!))) (p "Places string " (i "str") " in writer " (i "x") "'s buffer. Portions of " (i "str") " will be written to " (i "x") "'s file descriptor on subsequent calls to " (i "writer-write!") "."))) (section 5 "writer-write!" (def (sig (procedure " (writer-write! x) " (id writer-write!))) (p "Writes characters from writer " (i "x") "'s buffer to " (i "x") "'s file descriptor. Throws an exception if " (i "x") "'s file descriptor is not ready to be written to."))) (section 5 "writer-finished?" (def (sig (procedure " (writer-finished? x) " (id writer-finished?))) (p "Returns true if the writer " (i "x") " has nothing queued to be written to it's file descriptor. Otherwise returns false."))) (section 5 "Example" (p "Write the string \"hello, world!\\n\" to stdout using an async-io writer.") (highlight scheme "(use async-io posix)\n\n(define writer (make-writer fileno/stdout))\n\n(writer-enqueue! writer \"hello, world!\\n\")\n(let loop ()\n  (cond\n    ((writer-finished? writer)\n     (void))\n    ((writer-ready? writer)\n     (begin (writer-write! writer)\n            (loop)))\n    (else\n     (loop))))")))) (section 3 "About the Author" (p "Robert Smiley, the author of this egg can be reached at yarnoiserdev@gmail.com."))))