Version: 1.0
Original location: http://static.artfulcode.net/newlisp/sockets.lsp
Source: sockets.lsp
Package definition: sockets.qwerty
Classes for socket operations (requires newlisp 10)
Sockets are a fast, efficient method for client/server operations. newLisp
has a broad range of functions for dealing with socket-based connections,
many of them somewhat arcane if not familiar with socket jargon. The Sockets
module encapsulates some of this complexity into two simple classes.
The Socket class provides methods for reading, writing, and sending lisp
expressions between client and server processes. Requires newlisp 10+ and
unix sockets.
Version history
1.0
• initial release (replaces SocketServer module)
example: ; Fork a server
(setf pid
(fork
(let ((server (SocketServer "/tmp/newlisp.sock")))
(:run-server server
(lambda (client server , request)
(if client
(begin
(setf request (:read-expr client))
(eval request) ; not safe unless you know your client
(:write-expr client '(println "Hello, client!"))
(:close client))
(println "client connection error: " (net-error))))
nil ; no operations between connections
(lambda (err server) (println "An error has occurred: " err))))))
(sleep 500) ; give server time to start
; Connect to server process as a client
(let ((socket (Sockets:make-file-socket "/tmp/newlisp.sock")))
(:write-expr socket '(println "Hello, server!"))
(setf expr (:read-expr socket))
(:close socket))
(eval expr) ; not safe unless you know your server
(destroy pid) ; clean up
- § -
Sockets:make-file-socket
syntax: (Sockets:make-file-socket str-file)
parameter: str-file - a file to use as a socket file
Creates a new Socket instance using str-file
.
example: (setf socket (Sockets:create-socket-file "/tmp/my_app.sock"))
- § -
Sockets:make-network-socket
syntax: (Sockets:make-network-socket str-host int-port)
parameter: str-host - the HTTP hostname of the remote server
parameter: int-port - the remote server's port number to connect to
Creates a new Socket instance connected to str-host:int-port.
example: (setf socket (Sockets:create-network-soket "http://www.artfulcode.net" 80))
- § -
Socket
syntax: (Socket socket)
parameter: socket - an open socket file descriptor
A Socket is a wrapper around a socket file descriptor and uses the
built-in net-* functions to manage socket operations.
- § -
:socket
syntax: (:socket inst)
parameter: inst - an instance of Socket
Returns the socket file descriptor.
- § -
:close
syntax: (:close inst)
parameter: inst - an instance of Socket
Closes the socket connection.
- § -
:peek
syntax: (:peek inst)
parameter: inst - an instance of Socket
Returns the number of bytes ready to be read from the socket.
- § -
:ready?
syntax: (:ready? inst)
parameter: inst - an instance of Socket
Returns true if the socket is ready for reading.
- § -
:write
syntax: (:write inst str-message [int-chunk-size])
parameter: inst - an instance of Socket
parameter: str-message - the message to send
parameter: int-chunk-size - optional; sends message in chunks of size int-chunk-size
Sends str-message along the Socket. If optional int-chunk-size is
specified, sends the message in chunks.
- § -
:read-chunk
syntax: (:read-chunk inst int-bytes [block])
parameter: inst - an instance of Socket
parameter: int-bytes - the number of bytes to read
parameter: block - optional; if explicitly nil, does not block for bytes to be available
Blocks until a maximum of int-bytes are available to read from the
socket and then returns the resulting string. If blocks is explicitly
passed as nil, returns nil when no bytes are available to read.
- § -
:read
syntax: (:read inst [chunk-size [block]])
parameter: inst - an instance of Socket
parameter: chunk-size - the number of bytes to read at a time (default is 512)
parameter: block - whether to block for data (default is true)
Reads from the socket until there is nothing left to read. Will block
until something is available to read unless block is nil. This can lead
to an indefinitely blocking read if neither end closes the connection.
- § -
:read-line
syntax: (:read-line inst)
parameter: inst - an instance of Socket
Reads one line from the socket. Read-line will continue to read from
socket until and end-line character (\n or \r or both) is found. This
is not as fast as :read or :read-chunk, as it reads byte-by-byte, and
should not be used unless the source is trusted!
- § -
:write-expr
syntax: (:write-expr inst expr)
parameter: inst - an instance of Socket
parameter: expr - a quoted lisp expression
Sends expr along the socket. The other end of the socket may
then use :read-expr to read the expression back into lisp. Optionally,
expr may be a string, in which case it will be converted to the
expression '(string expr). Combined with :read-expr, this provides a
simple way to move complex data across a socket connection.
- § -
:read-expr
syntax: (:read-expr inst)
parameter: inst - an instance of Socket
Reads an expression from the socket. Returns a valid lisp expression.
This function will block until a valid lisp expression is encountered.
Combined with :write-expr, this provides a simple way to move complex
data across a socket connection.
- § -
SocketServer
syntax: (SocketServer int-port)
syntax: (SocketServer str-file)
parameter: int-port - the port number to listen on
parameter: str-file - alternately, the socket file to listen on
Creates a new SocketServer from a port number or socket file path.
SocketServer inherits directly from Socket, so all I/O methods from
Socket are available to SocketServer instances. Throws an error if it
encounters a problem creating the socket.
- § -
:accept
syntax: (:accept inst)
parameter: inst - an instance of SocketServer
Blocks until a connection is available and returns a new Socket
instance for the resulting connection.
- § -
:until-connection-ready
syntax: (:until-connection-ready inst func [poll-length])
parameter: inst - an instance of SocketServer
parameter: func - a function to call while awaiting a connection
parameter: poll-length - the number of ms to wait for a connection on each poll
Repeatedly calls func until a client connection is ready on the socket.
Optional parameter poll-timeout (milliseconds) controls the length of time
to wait for a connection before calling func. The function is passed the
server instance.
- § -
:on-connection
syntax: (:on-connection inst func)
parameter: inst - an instance of SocketServer
parameter: func - a function to call when a client connects
Blocks for a client connection and then calls func with the client
socket and the server instance. If an error occurs accepting the connection,
nil is passed to func. The error is then available via net-error.
- § -
:run-server
syntax: (:run-server inst func-connect [func-wait [func-err] [poll-length]])
parameter: inst - an instance of SocketServer
parameter: func-connect - called when a client connects
parameter: func-wait - called repeatedly while awaiting a client
parameter: func-err - called when a server error occurs
parameter: poll-length - the number of ms to wait for a connection on each poll
Runs the server in a loop. If func-connect is provided, it will be
called in the event of a server error. It is passed the error string and
server instance. If func-wait is provided, it will be called repeatedly
until a client connection is available. The only required parameters are the
SocketServer instance and func-connect, which will be called when a client
connection is accepted. It will be passed the client socket and the server
instance. If func-err is not defined, the server will throw an error when
an error occurs.
- ∂ -
generated with newLISP
and newLISPdoc