Project

Namespaces

Public Vars

teensyp.server

The main server namespace.

close

(close socket)(close socket callback)

Queue the supplied Socket to be closed. Accepts an optional, zero argument callback that will be run after the socket has been closed.

pause-reads

(pause-reads socket)(pause-reads socket callback)

Pause reads for this Socket. See: resume-reads. This is a control event, and is limited by the :control-queue-size. Too many control events queued at once for a single Socket will throw an ExceptionInfo.

resume-reads

(resume-reads socket)(resume-reads socket callback)

Resume reads for this Socket. Forces a call to the read handler if any data is waiting on the socket buffer. See: pause-reads. This is a control event, and is limited by the :control-queue-size. Too many control events queued at once for a single Socket will throw an ExceptionInfo.

Server

protocol

members

server-channel

(server-channel _)

Return the ServerSocketChannel for the Server.

Socket

protocol

A protocol representing a client socket. See also: write, close, pause-reads and resume-reads.

members

queue-control

(queue-control socket control callback)

Queue a control event, such as ::pause-reads or ::resume-reads.

queue-write

(queue-write socket buffer callback)

Queue the buffer to be written to the socket. If the callback is not nil, it will be called as a zero argument function once the buffer has been written. See write for a more convenient function.

socket-info

(socket-info socket)

Return a map of information about the socket’s connection. This includes keys for :local-address and :remote-address, which are immutable java.net.InetSocketAddress instances.

socket-lock

(socket-lock socket)

Return the ReentrantLock for the socket. Useful for guaranteeing multiple atomic writes.

try-write

(try-write socket buffer)

Try to immediately write as much of a buffer as it can to the socket without blocking. Returns true if the write completed in its entirity, false if it failed. See write for a more convenient function.

start-server

(start-server {:keys [port executor recv-buffer-size reuse-address?], :as opts})

Start a TCP server with the supplied map of options:

  • :port - the port number to listen on (mandatory)
  • :handler - a handler function (mandatory, see below)
  • :control-queue-size - the max number of queued control events (default 32)
  • :direct-read-buffer? - allocate a direct buffer for reads (default false)
  • :executor - a custom ExecutorService to supply worker threads
  • :read-buffer-size - the read buffer size in bytes (default 8K)
  • :recv-buffer-size - the receive buffer size (i.e. the SO_RCVBUF option)
  • :reuse-address? - sets the SO_REUSEADDR socket option (default false)
  • :write-buffer-size - the write buffer size in bytes (default 32K)
  • :write-queue-size - the max number of writes in the queue (default 64)

The handler function must have three arities:

(fn handler
  ([socket] initial-state)           ;; on socket accept
  ([state socket buffer] new-state)  ;; on socket read data
  ([state exception]))               ;; on socket close

The buffer is a java.nio.ByteBuffer instance, and socket is an object that satisfies the Socket protocol.

The state is a custom data structure that is returned when the accept or read arities are triggered. A different state is associated with each connection.

When closing, the exception may contain the exception that terminated the channel, or nil if the channel were terminated gracefully.

The handler function is guaranteed to execute in serial per channel. That is, the accept will always be first, the close will always be last, and reads will always be sequential.

The returned server instance implements java.io.Closeable, and therefore can be used with the with-open macro.

write

(write socket buffer)(write socket buffer callback)

Write a ByteBuffer to a socket defined by the Socket protocol. Accepts an optional, zero argument callback function that will be run after the buffer has been written.

The write will be attempted immediately; if the buffer could not be written in its entirity, the remaining bytes are queued to be written later. The callback function will only be called when all bytes are written to the socket.

The maximum number of queued buffers per socket is governed by the :write-queue-size option on the server, and the maximum size of bytes that can be held in all queued buffers is :write-buffer-size. Exceeding either of these limits will throw an ExceptionInfo.