commander/client

Table of Contents

System Information

Definition Index

• ORG.SHIRAKUMO.COMMANDER.CLIENT

  No documentation provided.

  • EXTERNAL CLASS

    CLIENT

    Source

    Representation of a basic client.
    
    The hostname and port to connect to on START can be passed as initargs.
    The additional initarg :RUN-SYNCHRONOUS, if passed as true, will cause
    START to execute RUN synchronously within the calling thread, rather
    than spinning up a separate thread.
    
    Depending on implementation support, the client may spin up another
    thread regardless though, in order to perform connection keepalive
    pings.
    
    See HOSTNAME
    See PORT
    See POLL-MESSAGE
    See WAIT-MESSAGE
    See PUMP-MESSAGES
    See HANDLE-MESSAGE
    See DEFINE-HANDLER
    See REMOTE-EVAL
    See EVAL-FROM-SERVER-ALLOWED-P
    See ORG.SHIRAKUMO.COMMANDER.SUPPORT:CLIENT

  • EXTERNAL CLASS

    DEBUGGER-CONTEXT

    Source

    Context representing a debugger's state.
    
    You may also use REMOTE-EVAL, QUERY, etc functions with this. If using
    the symbol constructor variant, the :THREAD initarg will be
    automatically injected according to the debugger context's thread.
    
    If STOP is called on the context, EXIT-DEBUGGER is sent to the server,
    causing it to try and escape to the nearest evaluation loop if any, or
    abort the thread entirely.
    
    See CLIENT
    See DEBUGGER-CONDITION
    See LEVEL
    See REPORT
    See THREAD
    See PROTO:ID
    See LOWER-DEBUGGER
    See ALIVE-P
    See QUERY
    See REMOTE-EVAL
    See STOP
    See HEADLESS (type)

  • EXTERNAL CLASS

    HEADLESS-CLIENT

    Source

    Client that is meant for headless use of a Commander server.
    
    This client type handles all other specified message types, and easily
    allows you to evaluate forms on the remote server. It also handles
    redirecting of io on server streams to streams on the client side.
    
    See FIND-STREAM
    See LIST-DEBUGGERS
    See ENTER-DEBUGGER
    See LEAVE-DEBUGGER
    See CLIENT (type)

  • EXTERNAL FUNCTION

    PUMP-MESSAGES

    • CLIENT
    • DURATION

    Source

    Handle messages for the given duration.
    
    Unlike WAIT-MESSAGE this will repeatedly handle messages until all of
    the given time budget is used up.
    
    See WAIT-MESSAGE
    See CLIENT (type)

  • EXTERNAL FUNCTION

    QUERY-ASYNC

    • ON-REPLY
    • CLIENT
    • MESSAGE
    • &REST
    • ARGS

    Source

    Send a query asynchronously, running ON-REPLY when a reply function is processed.
    
    In order to ensure that ON-REPLY is ever called, the HANDLE-MESSAGE
    function must be invoked for any V1:REPLY-type messages.
    
    Returns the sent message.
    
    See SEND!
    See QUERY
    See CLIENT (type)
    See WITH-DEFERRED-RESPONSE

  • EXTERNAL FUNCTION

    QUERY-UNWRAP

    • HANDLER
    • COMMAND
    • &REST
    • ARGS

    Source

    Convenience function to call UNWRAP-MESSAGE on QUERY.
    
    See QUERY
    See UNWRAP-MESSAGE

  • EXTERNAL GENERIC-FUNCTION

    ALIVE-P

    • THREADED

    Returns true if the threaded's thread is currently running.
    
    See START
    See STOP
    See THREADED (type)

  • EXTERNAL GENERIC-FUNCTION

    (SETF ALIVE-P)

    • NEW-VALUE
    • OBJECT

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    CLIENT

    • OBJECT

    Returns the client of the context.
    
    See CLIENT (type)
    See DEBUGGER-CONTEXT (type)

  • EXTERNAL GENERIC-FUNCTION

    (SETF CLIENT)

    • NEW-VALUE
    • OBJECT

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    CONNECTED-P

    • CLIENT

    Returns true if the client is still connected.
    
    Note that this does not guarantee that a write or read on the client's
    stream will succeed.
    
    See CLIENT (type)

  • EXTERNAL GENERIC-FUNCTION

    DEBUGGER-CONDITION

    • OBJECT

    Returns the condition representation that invoked the debugger.
    
    See ORG.SHIRAKUMO.COMMANDER.PROTOCOL.REFERENCE (type)
    See DEBUGGER-CONTEXT (type)

  • EXTERNAL GENERIC-FUNCTION

    ENTER-DEBUGGER

    • CLIENT
    • CONTEXT

    Function invoked when a debugger is entered on the server side.
    
    If the return-value is true, the debugger will be handled by this
    client. Otherwise the debugger will be declined and the server will
    decide what happens next.
    
    See HEADLESS-CLIENT (type)
    See DEBUGGER-CONTEXT (type)

  • EXTERNAL GENERIC-FUNCTION

    EVAL-FROM-SERVER-ALLOWED-P

    • OBJECT

    Accesses whether the server is allowed to send eval requests to this client.
    
    See CLIENT (type)

  • EXTERNAL GENERIC-FUNCTION

    (SETF EVAL-FROM-SERVER-ALLOWED-P)

    • NEW-VALUE
    • OBJECT

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    FIND-STREAM

    • ID
    • CLIENT

    Used to determine the corresponding stream to use on the client side.
    
    Users are encouraged to add methods on subclasses of HEADLESS-CLIENT
    that will return the intended streams to connect IO to.
    
    By default it will try to find a stream based on the identifier's
    symbol. If it is bound, that global binding value will be used. If
    not, then NIL is used as the identifier instead, which by default
    returns in a NIL return, rejecting the stream (and causing no IO to be
    connected).
    
    See HEADLESS-CLIENT (type)

  • EXTERNAL GENERIC-FUNCTION

    (SETF FIND-STREAM)

    • NULL
    • ID
    • CLIENT

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    HANDLE-MESSAGE

    • CLIENT
    • MESSAGE

    Process the given message.
    
    Users are encouraged to add methods to this function to handle message
    types for their client subclasses.
    
    For the default CLIENT class, the following message types are handled:
    
      V1:PING
      V1:CONNECT
      V1:DISCONNECT
      V1:OK
      V1:FAILURE
      V1:RETURN
    
    See ORG.SHIRAKUMO.COMMANDER.PROTOCOL.V1:PING
    See ORG.SHIRAKUMO.COMMANDER.PROTOCOL.V1:CONNECT
    See ORG.SHIRAKUMO.COMMANDER.PROTOCOL.V1:DISCONNECT
    See ORG.SHIRAKUMO.COMMANDER.PROTOCOL.V1:OK
    See ORG.SHIRAKUMO.COMMANDER.PROTOCOL.V1:RETURN
    See ORG.SHIRAKUMO.COMMANDER.PROTOCOL.V1:FAILURE
    See DEFINE-HANDLER
    See CLIENT (type)

  • EXTERNAL GENERIC-FUNCTION

    HOSTNAME

    • OBJECT

    Returns the hostname to which the client connects.
    
    See CLIENT (type)

  • EXTERNAL GENERIC-FUNCTION

    LEAVE-DEBUGGER

    • CLIENT
    • CONTEXT

    Function invoked when a debugger is exited on the server side.
    
    See HEADLESS-CLIENT (type)
    See DEBUGGER-CONTEXT (type)

  • EXTERNAL GENERIC-FUNCTION

    LEVEL

    • OBJECT

    Returns the debugger nesting level.
    
    The level may increase (and thus signify a debugger in a debugger) if
    an evaluation request within the debugger signals another error.
    
    See DEBUGGER-CONTEXT (type)

  • EXTERNAL GENERIC-FUNCTION

    LIST-DEBUGGERS

    • CLIENT

    Return a list of all active debugger contexts on the client.
    
    The list is sorted by most recent debugger first.
    
    See DEBUGGER-CONTEXT (type)
    See HEADLESS-CLIENT (type)

  • EXTERNAL GENERIC-FUNCTION

    LOWER-DEBUGGER

    • OBJECT

    Returns the debugger below this one's nesting level, if any.
    
    See LEVEL
    See DEBUGGER-CONTEXT (type)

  • EXTERNAL GENERIC-FUNCTION

    POLL-MESSAGE

    • CLIENT
    • &KEY
    • DEFAULT

    Return the next available message, if any.
    
    Returns DEFAULT if no message is available.
    
    See ORG.SHIRAKUMO.COMMANDER.SUPPORT:MINIQUEUE-POP
    See WAIT-MESSAGE
    See CLIENT (type)

  • EXTERNAL GENERIC-FUNCTION

    PORT

    • OBJECT

    Returns the port to which the client connects.
    
    See ORG.SHIRAKUMO.COMMANDER.PROTOCOL:*STANDARD-PORT*
    See CLIENT (type)

  • EXTERNAL GENERIC-FUNCTION

    QUERY

    • CLIENT
    • MESSAGE
    • &REST
    • ARGS
    • &KEY
    • TIMEOUT

    Send a query and block until a reply is received.
    
    Once a reply has been received, that message is returned. If the reply
    never arrives (because the client is stopped, its stream breaks, or
    some other error), then NIL is returned instead.
    
    If TIMEOUT is given it may be a real number indicating the maximum
    number of seconds to wait for a response before signalling a
    QUERY-TIMEOUT error.
    
    See SEND!
    See QUERY-ASYNC
    See QUERY-TIMEOUT (type)
    See CLIENT (type)

  • EXTERNAL GENERIC-FUNCTION

    REMOTE-EVAL

    • CLIENT
    • FORM
    • &KEY
    • PACKAGE
    • THREAD
    • PRINTED
    • TIMEOUT
    • &ALLOW-OTHER-KEYS

    Runs the FORM on the remote server the CLIENT is connected to.
    
    Note that FORM must be a Lisp form which can be turned to a string
    representation via PRIN1. Further, the code will be evaluated in the
    given package on the server side. If the package is NIL, the
    *PACKAGE* will be whatever it is on the server side already.
    
    Returns whatever values are returned on the server side after running
    them through PROTO:DEREFERENCE-RECURSIVELY with :ON-MISSING :IGNORE.
    Meaning that the values may contain protocol reference objects, if
    the objects referred to do not reside locally.
    
    The lisp form will be evaluated in a specific thread on the server
    side, which you can specify with the THREAD argument. By default this
    argument is the value of *DEFAULT-THREAD*. If THREAD is NIL, a new
    thread is spun up for this evaluation.
    
    See *DEFAULT-THREAD* (variable)
    See CLIENT (type)
    See WITH-REMOTE-EVAL

  • EXTERNAL GENERIC-FUNCTION

    REPLY-TO

    • CONDITION

    The ID of the message to which this failure relates.
    
    See QUERY-FAILURE (type)

  • EXTERNAL GENERIC-FUNCTION

    REPORT

    • OBJECT

    Returns the error report.
    
    See DEBUGGER-CONTEXT (type)

  • EXTERNAL GENERIC-FUNCTION

    RUN

    • THREADED

    Source

    The function to run within the THREADED's thread.
    
    Within primary methods of RUN, the threaded's THREAD is set, and the
    STOP restart is active.
    
    See THREADED (type)

  • EXTERNAL GENERIC-FUNCTION

    SEND

    • CLIENT
    • MESSAGE
    • &REST
    • ARGS
    • &KEY

    Sends a message over the client's stream.
    
    MESSAGE may either be a PROTO:MESSAGE instance, in which case ARGS are
    ignored, or a symbol naming a constructor function to which ARGS are
    passed before SENDing it out.
    
    While writing the message to the stream, the WRITE-LOCK is acquired to
    ensure no interleaved writes occur.
    
    Unlike SEND!, this function does not flush the underlying stream.
    
    See WRITE-LOCK
    See CLIENT (type)
    See SEND

  • EXTERNAL GENERIC-FUNCTION

    SEND!

    • CLIENT
    • MESSAGE
    • &REST
    • ARGS
    • &KEY

    Sends a message over the client's stream immediately.
    
    Like SEND, but flushes the stream.
    
    Returns the sent message.
    
    See SEND
    See CLIENT (type)

  • EXTERNAL GENERIC-FUNCTION

    START

    • THREADED

    Source

    Starts the threaded if it is not yet alive.
    
    Upon return, ALIVE-P should be true.
    
    See THREADED (type)
    See ALIVE-P

  • EXTERNAL GENERIC-FUNCTION

    STOP

    • THREADED

    Source

    Stops the threaded if it is currently alive.
    
    If this is executed within the thread managed by the threaded, then
    the STOP restart is invoked. Otherwise if the thread is alive, the
    STOP restart is invoked within it.
    
    After calling this function, ALIVE-P should be false.
    
    See THREADED (type)
    See ALIVE-P

  • EXTERNAL GENERIC-FUNCTION

    THREAD

    • OBJECT

    The thread that the object manages, if any.
    
    See THREADED (type)
    See ALIVE-P

  • EXTERNAL GENERIC-FUNCTION

    (SETF THREAD)

    • NEW-VALUE
    • OBJECT

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    WAIT-MESSAGE

    • CLIENT
    • &KEY
    • TIMEOUT
    • TEST

    Wait for the next available message.
    
    TEST can be used to specify a filter for susceptible messages.
    TIMEOUT can be used to specify a maximum number of seconds to wait for
    before returning.
    
    See ORG.SHIRAKUMO.COMMANDER.SUPPORT:MINIQUEUE-FIND-IF
    See POLL-MESSAGE
    See PUMP-MESSAGES
    See CLIENT (type)

  • EXTERNAL MACRO

    DEFINE-HANDLER

    • CLASS
    • TYPE
    • &REST
    • QUALIFIERS
    • ARGS
    • &BODY
    • BODY

    Source

    Shorthand function to define a message type handler method.
    
    CLASS should be the name of the client class this handler is for. The
    client instance is also bound to this variable.
    TYPE should be the name of the message type to handle.
    ARGS can be a list of fields of the message to bind within the body of
    the handler, via the use of WITH-FIELDS.
    
    Within BODY, the following extra functions are available, each bound
    to names in the current package:
    
      SEND  --- Shorthand for SEND! on the current client.
      REPLY --- Shorthand to use SEND with the current message's ID
                supplied as the :REPLY-TO initarg for the new message.
      OK    --- Shorthand to send an V1:OK reply.
      RET   --- Shorthand to send a V1:RETURN reply.
      FAIL  --- Shorthand to send a V1:FAILURE reply.
    
    See HANDLE-MESSAGE
    See ORG.SHIRAKUMO.COMMANDER.PROTOCOL:WITH-FIELDS
    See ORG.SHIRAKUMO.COMMANDER.PROTOCOL.V1:OK
    See ORG.SHIRAKUMO.COMMANDER.PROTOCOL.V1:RETURN
    See ORG.SHIRAKUMO.COMMANDER.PROTOCOL.V1:FAILURE
    See CLIENT (type)

  • EXTERNAL MACRO

    WITH-CLIENT

    • VAR
    • CLIENT
    • &REST
    • INITARGS
    • &BODY
    • BODY

    Source

    Helper macro to lexically bind a client.
    
    Instantiates a CLIENT, binds it to VAR, calls START on the client, and
    then evaluates BODY forms. On exit from the body, STOP is called on
    the client.
    
    CLIENT can be either a CLIENT instance, or the name of a client class
    to construct via MAKE-INSTANCE.
    
    See CLIENT (type)

  • EXTERNAL MACRO

    WITH-DEFERRED-RESPONSE

    • CLIENT
    • CONSTRUCTOR
    • &REST
    • ARGS
    • VALS
    • &BODY
    • BODY

    Source

    Convenience macro around QUERY-ASYNC.
    
    VALS are bound to the values returned by UNWRAP-MESSAGE and BODY is
    evaluated when the query returns, in whichever thread handles that
    message.
    
    See QUERY-ASYNC

  • EXTERNAL MACRO

    WITH-REMOTE-EVAL

    • CLIENT
    • &REST
    • ARGS
    • &BODY
    • BODY

    Source

    Shorthand macro to evaluate the body forms on the remote server.
    
    This is a convenience around REMOTE-EVAL.
    
    See REMOTE-EVAL

  • EXTERNAL MACRO

    WITH-REMOTE-REPL

    • CLIENT
    • &OPTIONAL
    • REPL
    • NAME
    • &BODY
    • BODY

    Source

    Shorthand macro to create a remote REPL.
    
    During the body, *DEFAULT-THREAD* is bound to the REPL's thread so you
    can call REMOTE-EVAL without needing to pass it explicitly.
    
    See *DEFAULT-THREAD*
    See REMOTE-EVAL