start-up-server &key function announce service address local-address local-port nodelay keepalive process-name wait error => process, startup-condition
A function name.
An output stream, t, nil or a function.
An integer, a string or nil.
nil or a positive integer.
A synonym for local-address.
An integer, an ipv6-address object, a string or nil.
A synonym for service.
A generalized boolean.
A generalized boolean.
A symbol or expression.
A boolean.
The keyword :any, the keyword :both, nil or t.
A boolean.
The function start-up-server starts a TCP server. Use open-tcp-stream to send messages from another client to the server.
The function argument provides the name of the function that processes connections. When a connection is made function is called with the connected socket handle, at which point you can make a stream using make-instance and communicate with the client. The server does not accept more connections until function returns, so normally it should create another light-weight process to handle the connection. However, the operating system typically provides a small queue of partially accepted connections, which prevents connection failure for new clients until the server is ready to accept more connections. If function is not specified the built-in Lisp listener server is used. See the examples section below.
If announce is a stream or t (denoting *standard-output*), a message appears on the stream when the server is started.
If announce is a function it is called when the server is started. announce should take two arguments: socket and condition. socket is the socket used by the server: announce can therefore be used to record this socket. condition describes the error if there is one. announce can be called with socket nil and a condition only if error is nil. If the process is killed, announce is called with socket nil and condition nil.
The default for announce is nil, meaning there is no message.
service is interpreted as described in Specifying the target for connecting and binding a socket. The default value of service is a string "lispworks".
backlog specifies the maximum number of pending connections for the socket in the operating system (see your operating system's documentation for the function listen). The default value of backlog is 5.
If local-address is nil then the server will receive connections to all IP addresses on the computer. If local-address is non-nil then the server only receives connections for the IP address that local-address specifies. The default value of local-address is nil.
address also determines which family is used when making the socket. AF_INET6 is used in these cases:
Otherwise AF_INET is used. When address is not supplied, AF_INET is used. To open a server with AF_INET6 listening to any address, either use the keyword argument ipv6 or pass the zero IPv6 address "::".
If keepalive is true, SO_KEEPALIVE is set on the socket. The default value of keepalive is nil.
If nodelay is true, TCP_NODELAY is set on the socket. The default value of nodelay is t.
The process-name specifies the process name. The default is constructed from the service name in the following fashion:
(format nil "~S server" service)
The wait argument controls whether start-up-server waits for the server to start or returns immediately. When wait is non-nil and an error was signaled, process is nil and the error is returned in startup-condition Otherwise just one value, the server process, is returned. The default for wait is nil.
ipv6 affects the resolution of address if it is a string or nil. When ipv6 is nil, it forces IPv4 addresses, and if ipv6 is t it forces IPv6 addresses. When ipv6 is :any the system tries either IPv4 or IPv6 and uses the first socket that it succeeds to bind. When ipv6 is :both the system uses IPv6 (like the value t) but allows connection requests in IPv4. Note that with t only IPv6 connections are allowed. The default value of ipv6 is :any.
The error argument controls what happens if an error is signaled in the server thread. If error is nil then the thread is terminated. If error is non-nil then the debugger is entered. The default value for error is (not wait).
start-up-server as its argument, or call server-terminate from the function supplied to start-up-server.t, it is possible to listen separately for IPv4 connections on the same service (by another service or using the Asynchronous I/O API). When using :both, it is not possible to listen separately to IPv4 on the same service.nil, the port that the underlying system assigned to the first socket is used for opening the socket again. One situation that invokes that mechanism is putting an iOS device to sleep, which causes the accepting socket to become broken in a non-obvious way.
In LispWorks 6.1 and previous versions, the argument ipv6 t means either accepting IPv4 or not, depending on the default of the operating system. In LispWorks 7.0 and later ipv6 t means never allow IPv4 connections.
The following example uses the built-in Lisp listener server:
(comm:start-up-server :service 10243)
It makes a Lisp listener server on port 10243 (check with local network managers that this port number is safe to use). When a client connects to this, Lisp calls read. The client should send a string using Common Lisp syntax followed by a newline. This string is used to name a new light-weight process that runs a Lisp listener. When this has been created, the server waits for more connections.
The next example illustrates the use of the function argument. For each line of input read by the server it writes the line back with a message. The stream generates EOF if the other end closes the connection.
(defvar *talk-port* 10244) ; a free TCP port number
(defun make-stream-and-talk (handle)
(let ((stream (make-instance 'comm:socket-stream
:socket handle
:direction :io
:element-type
'base-char)))
(mp:process-run-function (format nil "talk ~D"
handle)
'()
'talk-on-stream stream)))
(defun talk-on-stream (stream)
(unwind-protect
(loop for line = (read-line stream nil nil)
while line
do
(format stream "You sent: '~A'~%" line)
(force-output stream))
(close stream)))
(comm:start-up-server :function 'make-stream-and-talk
:service *talk-port*)
This is a client which uses the talk server:
(defun talking-to-myself ()
(with-open-stream
(talk (comm:open-tcp-stream "localhost"
*talk-port*))
(dolist (monolog
'("Hello self."
"Why don't you say something original?"
"Talk to you later then. Bye."))
(write-line monolog talk)
(force-output talk)
(format t "I said: \"~A\"~%"
monolog)
(format t "Self replied: \"~A\"~%"
(read-line talk nil nil)))))
(talking-to-myself)
=>
I said: "Hello self."
Self replied: "You sent: 'Hello self.'"
I said: "Why don't you say something original?"
Self replied: "You sent: 'Why don't you say something original?'"
I said: "Talk to you later then. Bye."
Self replied: "You sent: 'Talk to you later then. Bye.'"
This example illustrates a server which picks a free port and records the socket. The last form queries the socket for the port used.
(defvar *my-socket* nil)
(defun my-announce-function (socket condition)
(if socket
(setf *my-socket* socket)
(my-log-error condition)))
(comm:start-up-server :service nil
:error nil
:announce 'my-announce-function)
(multiple-value-bind (address port)
(comm:get-socket-address *my-socket*)
port)
LispWorks User Guide and Reference Manual - 20 Sep 2017