cl-async

API Reference

cl-async

Asynchronous operations for Common Lisp.

CL-ASYNC

  • Function ADD-EVENT-LOOP-EXIT-CALLBACK (fn)
    Add a function to be run when the event loop exits.
  • Generic-Function REF (handle)
    Reference a libuv handle object (uv_ref)
  • Generic-Function UNREF (handle)
    Unreference a libuv handle object (uv_unref)
  • Function STATS
    Return statistics about the current event loop.
  • Function DUMP-EVENT-LOOP-STATUS
    Return the status of the event loop. Really a debug function more than anything else.
  • Function START-EVENT-LOOP (start-fn &key catch-app-errors (send-errors-to-eventcb t))
    Simple wrapper function that starts an event loop which runs the given callback, most likely to init your server/client.
  • Macro WITH-EVENT-LOOP ((&key catch-app-errors (send-errors-to-eventcb t)) &body body)
    Makes starting an event loop a tad less annoying. I really couldn't take typing out `(start-event-loop (lambda () ...) ...) every time. Example: (with-event-loop (:catch-app-errors t) (do-something-one-does-when-an-event-loop-is-running)) See how nice that is?
  • Function EXIT-EVENT-LOOP
    Exit the event loop if running.
  • Condition EVENT-FREED  (EVENT-ERROR)
    Thrown when a freed event is operated on.
  • Class EVENT
    Wraps a C libuv event object.
    C   Accessor: EVENT-C
    FREED   Accessor: EVENT-FREED   Reader: EVENT-FREED-P
  • Function FREE-EVENT (event)
    Free a cl-async event object and any resources it uses.
  • Function REMOVE-EVENT (event)
    Remove a pending event from the event loop.
  • Method REF ((handle event))
  • Method UNREF ((handle event))
  • Function ADD-EVENT (event &key timeout activate)
    Add an event to its specified event loop (make it pending). If given a :timeout (in seconds) the event will fire after that amount of time, unless it's removed or freed.
  • Function DELAY (callback &key time event-cb)
    Run a function, asynchronously, after the specified amount of seconds. An event loop must be running for this to work. If time is nil, callback is still called asynchronously, but is queued in the event loop with no delay.
  • Macro WITH-DELAY ((&optional (seconds 0)) &body body)
    Nicer syntax for delay function.
  • Function INTERVAL (callback &key time event-cb)
    Run a function, asynchronously, every `time` seconds. This function returns a function which, when called, cancels the interval.
  • Macro WITH-INTERVAL ((seconds) &body body)
    Nicer syntax for interval function.
  • Function REMOVE-INTERVAL (interval-fn)
    Stops an interval from looping.
  • Function MAKE-EVENT (callback &key event-cb)
    Make an arbitrary event, and add it to the event loop. It *must* be triggered by (add-event <the event> :activate t) or it will sit, idle, for 100 years. Or you can remove/free it instead. This is useful for triggering arbitrary events, and can even be triggered from a thread outside the libuv loop.
  • Condition DNS-ERROR  (EVENT-ERROR)
    Passed to a failure callback when a DNS error occurs on a connection.
  • Function DNS-LOOKUP (host resolve-cb &key event-cb (family +af-inet+))
    Asynchronously lookup a DNS address. Note that if an IP address is passed, the lookup happens synchronously. If a lookup is synchronous (and instant) this returns T, otherwise nil (lookup happening in background). Either way the resolve-cb is called with the lookup info (so always assume this is async).
  • Function REVERSE-DNS-LOOKUP (ip resolve-cb &key event-cb)
    Perform reverse DNS lookup on IP specifier as string. Call RESOLVE-CB with resolved HOST and SERVICE as strings. The callback is called once with one host, even if multiple hosts match the query.
  • Condition STREAMISH-INFO  (EVENT-INFO)
    Base streamish condition. Holds the streamish object.
  • Condition STREAMISH-ERROR  (EVENT-ERROR, STREAMISH-INFO)
    Describes a general streamish error.
  • Condition STREAMISH-EOF  (STREAMISH-INFO)
    Passed to an event callback when stream EOF is reached.
  • Condition STREAMISH-CLOSED  (STREAMISH-ERROR)
    Thrown when a closed streamish is being operated on.
  • Condition STREAMISH-BROKEN-PIPE  (STREAMISH-ERROR)
    Broken pipe.
  • Condition STREAMISH-CANCELED  (STREAMISH-ERROR)
    Operation canceled.
  • Class STREAMISH
    Wraps around a streamish.
    C   Accessor: STREAMISH-C
    DATA   Accessor: STREAMISH-DATA
    Used to store arbitrary (app-defined) data with a streamish.
    CLOSED   Accessor: STREAMISH-CLOSED
    DRAIN-READ-BUFFER   Accessor: STREAMISH-DRAIN-READ-BUFFER
  • Generic-Function STREAMISH (thing)
    Returned associated streamish for THING or THING itself if THING is a streamish.
  • Function CHECK-STREAMISH-OPEN (streamish)
    Throw a streamish-closed condition if given a streamish that's closed.
  • Function STREAMISH-CLOSED-P (streamish)
    Return whether a streamish is closed or not.
  • Generic-Function CLOSE-STREAMISH (streamish &key &allow-other-keys)
    Free a streamish (uvstream) and clear out all associated data.
  • Method CLOSE-STREAMISH ((streamish streamish) &key force)
    Close and free a streamish and all of it's underlying structures.
  • Generic-Function STREAMISH-WRITE (streamish data &key start end &allow-other-keys)
    Write data into a streamish. Allows specifying read/write/event callbacks. Any callback left nil will use that current callback from the streamish (so they only override when specified, otherwise keep the current callback). Note that libuv doesn't buffer output for non-connected sockets, so we have to do it ourselves by checking if the socket is connected and buffering accordingly.
  • Method STREAMISH-WRITE ((streamish streamish) data &key start end &allow-other-keys)
  • Method STREAMISH-WRITE ((streamish streamish) data &key read-cb write-cb event-cb &allow-other-keys)
  • Class ASYNC-STREAM  (TRIVIAL-GRAY-STREAM-MIXIN)
    The underlying class for async streams. Wraps a streamish.
    STREAMISH   Accessor: STREAMISH
    BUFFER   Accessor: STREAM-BUFFER
  • Class ASYNC-OUTPUT-STREAM  (ASYNC-STREAM, FUNDAMENTAL-BINARY-OUTPUT-STREAM)
    Async output stream.
    No slots.
  • Class ASYNC-INPUT-STREAM  (ASYNC-STREAM, FUNDAMENTAL-BINARY-INPUT-STREAM)
    Async input stream.
    No slots.
  • Class ASYNC-IO-STREAM  (ASYNC-INPUT-STREAM, ASYNC-OUTPUT-STREAM)
    Async stream for both input and output.
    No slots.
  • Function STREAM-SOCKET (stream)
  • Condition SOCKET-INFO  (STREAMISH-INFO)
    Base socket condition. Holds the socket object.
  • Condition SOCKET-ERROR  (STREAMISH-ERROR, SOCKET-INFO)
    Describes a general socket connection error.
  • Condition SOCKET-EOF  (STREAMISH-EOF, SOCKET-ERROR)
    Peer closes a socket connection.
  • Condition SOCKET-RESET  (SOCKET-ERROR)
    Connection reset.
  • Condition SOCKET-TIMEOUT  (SOCKET-ERROR)
    Socket connection timed out.
  • Condition SOCKET-REFUSED  (SOCKET-ERROR)
    Connection refused.
  • Condition SOCKET-ABORTED  (SOCKET-ERROR)
    Connection aborted.
  • Condition SOCKET-ADDRESS-IN-USE  (SOCKET-ERROR)
    Address is already in use.
  • Condition SOCKET-ACCEPT-ERROR  (SOCKET-ERROR)
    Passed to a server's event-cb when there's an error accepting a connection.
  • Type SOCKET-CLOSED
  • Class SOCKET  (STREAMISH)
    Wraps around a socket.
    C   Accessor: SOCKET-C
    DATA   Accessor: SOCKET-DATA
    CLOSED   Accessor: SOCKET-CLOSED
    BUFFER   Accessor: SOCKET-BUFFER
    Holds data sent on the socket that hasn't been sent yet.
    BUFFERINGP   Accessor: SOCKET-BUFFERING-P
    Lets us know if the socket is currently buffering output.
    CONNECTED   Accessor: SOCKET-CONNECTED
    DRAIN-READ-BUFFER   Accessor: SOCKET-DRAIN-READ-BUFFER
  • Generic-Function CLOSE-SOCKET-SERVER (socket)
    Closes a socket server. If already closed, does nothing.
  • Method CLOSE-SOCKET-SERVER ((socket-server socket-server))
  • Function SET-SOCKET-TIMEOUTS (socket read-sec write-sec &key socket-is-uvstream)
    Set the read/write timeouts on a socket.
  • Function ENABLE-SOCKET (socket &key read write)
    Enable read/write monitoring on a socket. If :read or :write are nil, they are not disabled, but rather just not enabled.
  • Function DISABLE-SOCKET (socket &key read write)
    Disable read/write monitoring on a socket. If :read or :write are nil, they are not enabled, but rather just not disabled.
  • Method STREAMISH-WRITE ((socket socket) data &key start end force &allow-other-keys)
  • Method CLOSE-STREAMISH ((socket socket) &key force &allow-other-keys)
  • Function WRITE-SOCKET-DATA (socket data &rest args &key &allow-other-keys)
    An compatibility alias for STREAMISH-WRITE.
  • Function SOCKET-CLOSED-P (socket)
    Return whether a socket is closed or not. Same as streamish-closed-p.
  • Function CLOSE-SOCKET (socket &key force)
    Free a socket (uvstream) and clear out all associated data. Same as close-streamish.
  • Method SOCKET ((thing t))
  • Type TCP-EOF
  • Type TCP-INFO
  • Type TCP-ERROR
  • Type TCP-RESET
  • Type TCP-TIMEOUT
  • Type TCP-REFUSED
  • Type TCP-ACCEPT-ERROR
  • Condition TCP-SERVER-BIND-ERROR  (SOCKET-ERROR)
    Thrown when a server fails to bind (generally, the port is already in use).
  • Class TCP-SOCKET  (TCP-MIXIN, SOCKET)
    DIRECTION   Accessor: SOCKET-DIRECTION
  • Class TCP-SERVER  (TCP-MIXIN, SOCKET-SERVER)
    No slots.
  • Method CLOSE-STREAMISH ((socket tcp-socket) &key &allow-other-keys)
  • Function CONNECT-TCP-SOCKET (socket/stream host port &key event-cb)
    Connect a tcp socket initialized with init-client-socket.
  • Function TCP-CONNECT (host port read-cb &rest args)
    Open a TCP connection asynchronously. Optionally send data out once connected via the :data keyword (can be a string or byte array).
  • Function TCP-SERVER (bind-address port read-cb &rest args)
    Open a TCP connection asynchronously. Optionally send data out once connected via the :data keyword (can be a string or byte array).
  • Function CLOSE-TCP-SERVER (server)
  • Condition FILESYSTEM-ERROR  (EVENT-ERROR)
    Base class for filesystem conditions
  • Condition FILESYSTEM-ENOENT  (FILESYSTEM-ERROR)
    Error: no such file or directory
  • Condition FILESYSTEM-EACCES  (FILESYSTEM-ERROR)
    Error: access denied
  • Condition FILESYSTEM-EPERM  (FILESYSTEM-ERROR)
    Error: permission denied
  • Function MKDTEMP (template cb &key (event-cb #'error))
  • Class PIPE-SERVER  (PIPE-MIXIN, SOCKET-SERVER)
    No slots.
  • Function PIPE-CONNECT (name read-cb &key data stream event-cb connect-cb write-cb (read-timeout -1) (write-timeout -1) (dont-drain-read-buffer nil dont-drain-read-buffer-supplied-p))
    Open a pipe connection asynchronously. Optionally send data out once connected via the :data keyword (can be a string or byte array).
  • Function PIPE-SERVER (name read-cb &key event-cb connect-cb backlog stream fd)
    Start a pipe listener on the current event loop. Returns a tcp-server class which can be closed with close-tcp-server
  • Variable +SIGHUP+
    1
  • Variable +SIGINT+
    2
  • Variable +SIGQUIT+
    3
  • Variable +SIGILL+
    4
  • Variable +SIGTRAP+
    5
  • Variable +SIGABRT+
    6
  • Variable +SIGEMT+
    7
  • Variable +SIGFPE+
    8
  • Variable +SIGKILL+
    9
  • Variable +SIGBUS+
    10
  • Variable +SIGSEGV+
    11
  • Variable +SIGSYS+
    12
  • Variable +SIGPIPE+
    13
  • Variable +SIGALRM+
    14
  • Variable +SIGTERM+
    15
  • Variable +SIGURG+
    16
  • Variable +SIGSTOP+
    17
  • Variable +SIGTSTP+
    18
  • Variable +SIGCONT+
    19
  • Variable +SIGCHLD+
    20
  • Variable +SIGTTIN+
    21
  • Variable +SIGTTOU+
    22
  • Variable +SIGIO+
    23
  • Variable +SIGXCPU+
    24
  • Variable +SIGXFSZ+
    25
  • Variable +SIGVTALRM+
    26
  • Variable +SIGPROF+
    27
  • Variable +SIGWINCH+
    28
  • Variable +SIGINFO+
    29
  • Variable +SIGUSR1+
    30
  • Variable +SIGUSR2+
    31
  • Function FREE-SIGNAL-HANDLER (signo)
    Clear a signal handler and unbind it.
  • Function CLEAR-SIGNAL-HANDLERS
    Clear all bound signal handlers. Great for cleaning up when exiting an app.
  • Function SIGNAL-HANDLER (signo signal-cb &key event-cb)
    Setup a one-time signal handler for the given signo. This also sets up a lisp signal handler, so if a signal comes through while lisp is running instead of the event loop, it will run the same callback. All signal handlers are restored on event loop exit.
  • Class NOTIFIER
    Wraps a threading-enabled notifier.
    C   Accessor: NOTIFIER-C
    FREED   Accessor: NOTIFIER-FREED   Reader: NOTIFIER-FREED-P
    SINGLE-SHOT   Accessor: NOTIFIER-SINGLE-SHOT   Reader: NOTIFIER-SINGLE-SHOT-P
  • Function FREE-NOTIFIER (notifier)
    Free a cl-async notifier object and any resources it uses.
  • Method REF ((handle notifier))
  • Method UNREF ((handle notifier))
  • Function MAKE-NOTIFIER (callback &key event-cb (single-shot t))
    Makes a notifier, an object that can trigger a callback from a thread other than the event loop thread. If single-shot is true (the default), free the notifier after it's triggered.
  • Function TRIGGER-NOTIFIER (notifier)
    Fires the callback attached to a notifier. Can be called from any thread.
  • Class POLLER
    Wraps a polling handle.
    C   Accessor: POLLER-C
    FREED   Accessor: POLLER-FREED   Reader: POLLER-FREED-P
  • Function FREE-POLLER (poller)
    Stop and free a poller.
  • Function POLL (fd poll-cb &key event-cb (poll-for '(:readable :writable)) socket)
    Poll an OS FD. If the FD is a socket, :socket t must be passed.
  • Class IDLER
    Wraps a libuv idle handle.
    C   Accessor: IDLER-C
    FREED   Accessor: IDLER-FREED   Reader: IDLER-FREED-P
  • Function FREE-IDLER (idler)
    Stop and free an idler.
  • Function IDLE (callback &key event-cb)
    Calls `callback` once per event loop.
  • Function SPAWN (path args &key exit-cb (event-cb #'error) (input :ignore) (output :ignore) (error-output :ignore))
    Run the program specified by PATH with specified ARGS. ARGS don't include the executable path (argv[0]). Return process object and pipes or streams for input, output and error output file descriptors of the child process (NIL for file descriptors that aren't redirected via :PIPE or :STREAM, see below). EXIT-CB specifies the callback that should be called when the program terminates. It should be a function taking three arguments: process object, exit status and signal number that caused program termination (0 if the program wasn't terminated by signal). EVENT-CB specifies error handler to be used. INPUT, OUTPUT and ERROR-OUTPUT specify process input/output/error output redirection. For each of these, the following values are supported: :IGNORE the corresponding file descriptor isn't used :INHERIT inherit file descriptor from this process (:PIPE [:READ-CB ...] ...) use pipe-based redirection of the corresponding file descriptor (see PIPE-CONNECT for the set of supported keyword arguments). (:STREAM [:READ-CB ...] ...) same as PIPE, but uses async stream instead of a pipe.
  • Function PROCESS-KILL (process signal &key (event-cb #'error))
    If PROCESS is active, send the specified signal (an integer) to it and return true. If PROCESS is not active or an error occurs (and EVENT-CB doesn't signal an error), return false. If EVENT-CB is specified, use it to handle errors, otherwise signal them via ERROR.
  • Function FS-MONITOR-CLOSE (fs-monitor)
  • Function FS-WATCH (path callback &key (event-cb #'error))
  • Function FS-UNWATCH (fs-monitor)

Also exports

  • CL-ASYNC-BASE:EVENT-INFO
  • CL-ASYNC-BASE:*BUFFER-SIZE*
  • CL-ASYNC-BASE:EVENT-ERRMSG
  • CL-ASYNC-UTIL:BYTES
  • CL-ASYNC-BASE:EVENT-ERROR
  • CL-ASYNC-BASE:EVENT-ERRCODE
  • CL-ASYNC-UTIL:HANDLE-ERROR
  • CL-ASYNC-UTIL:+AF-INET+
  • CL-ASYNC-UTIL:OCTET
  • CL-ASYNC-UTIL:+AF-UNIX+
  • CL-ASYNC-UTIL:OCTET-VECTOR
  • CL-ASYNC-UTIL:+AF-UNSPEC+
  • CL-ASYNC-UTIL:+AF-INET6+
  • CL-ASYNC-BASE:*BUFFER-WRITES*

cl-async-repl

REPL integration for CL-ASYNC.

CL-ASYNC-REPL

  • Function EVENT-THREAD-RUNNING-P
    Returns true if the event thread used by async REPL is running
  • Function START-ASYNC-REPL (&optional on-startup)
    Start event thread and install SLIME REPL hook so that everything is evaluated in that thread. Stopping the event loop via (as:stop-event-thread) removes the hook. If ON-STARTUP function is specified, it's executed in the event loop thread after it's started. Sets *safe-sldb-quit-restart* to true.
  • Function ENSURE-ASYNC-REPL (&optional on-startup)
    If event loop is not started, calls START-ASYNC-REPL passing ON-STARTUP to it. If it's already started, calls ON-STARTUP if it's not null.
  • Function STOP-ASYNC-REPL
    Stop event thread and uninstall SLIME REPL hook. Sets *safe-sldb-quit-restart* to false.

cl-async-ssl

SSL Wrapper around cl-async socket implementation.

CL-ASYNC-SSL

  • Variable +SSL-VERIFY-NONE+
    0
  • Variable +SSL-VERIFY-PEER+
    1
  • Variable +SSL-VERIFY-FAIL-IF-NO-PEER-CERT+
    2
  • Variable +SSL-VERIFY-CLIENT-ONCE+
    4
  • Variable +SSL-OP-ALL+
    2147486719
  • Variable +SSL-OP-NO-QUERY-MTU+
    4096
  • Variable +SSL-OP-COOKIE-EXCHANGE+
    8192
  • Variable +SSL-OP-NO-TICKET+
    16384
  • Variable +SSL-OP-CISCO-ANYCONNECT+
    32768
  • Variable +SSL-OP-NO-SESSION-RESUMPTION-ON-RENEGOTIATION+
    65536
  • Variable +SSL-OP-NO-COMPRESSION+
    131072
  • Variable +SSL-OP-ALLOW-UNSAFE-LEGACY-RENEGOTIATION+
    262144
  • Variable +SSL-OP-SINGLE-ECDH-USE+
    524288
  • Variable +SSL-OP-SINGLE-DH-USE+
    1048576
  • Variable +SSL-OP-EPHEMERAL-RSA+
    2097152
  • Variable +SSL-OP-CIPHER-SERVER-PREFERENCE+
    4194304
  • Variable +SSL-OP-TLS-ROLLBACK-BUG+
    8388608
  • Variable +SSL-OP-NO-SSLV2+
    16777216
  • Variable +SSL-OP-NO-SSLV3+
    33554432
  • Variable +SSL-OP-NO-TLSV1+
    67108864
  • Variable +SSL-OP-NO-TLSV1-2+
    134217728
  • Variable +SSL-OP-NO-TLSV1-1+
    268435456
  • Condition TCP-SSL-ERROR  (TCP-ERROR)
    Describes a general SSL connection error.
  • Class SSL-SOCKET  (SOCKET)
    Extends cl-async's socket to hold SSL info
    AS-SSL   Accessor: SOCKET-AS-SSL
    SSL-BUFFER   Accessor: SOCKET-SSL-BUFFER
    SSL-CONNECTED   Accessor: SOCKET-SSL-CONNECTED
    SSL-CLOSING   Accessor: SOCKET-SSL-CLOSING
    SSL-FUNCTION   Accessor: SOCKET-SSL-FUNCTION
  • Class TCP-SSL-SERVER  (TCP-SERVER)
    Wraps around an SSL server/listener
    AS-SSL   Accessor: TCP-SERVER-AS-SSL
  • Function TCP-SSL-CONNECT (host port read-cb &rest args)
    Open a TCP connection asynchronously. Optionally send data out once connected via the :data keyword (can be a string or byte array).
  • Function TCP-SSL-SERVER (bind-address port read-cb &rest args)
    Open a TCP connection asynchronously. Optionally send data out once connected via the :data keyword (can be a string or byte array).

cl-async-test

TESTS FOR Asynchronous operations for Common Lisp.

CL-ASYNC-TEST

  • Function BENCHMARK-SERVER (&key (port 9009) (request-delay 0) (num-requests 40000))
  • Function BENCHMARK-CLIENT (&key (server "127.0.0.1") (port 9009) (num-requests 40000) (delay 1) (client-id 0))
  • Function RUN-TESTS (&key ssl threading)