Place TCP Listener

8.16.0.1

Place TCP Listener🔗ℹ

This package provides an implementation of a TCP listener that accepts connections and dispatches them to places, enabling its users to parallelize their TCP servers, similar to the implementation described in Parallelizing the Racket Web Server.

1 Reference🔗ℹ

(require net/place-tcp)

package: place-tcp-listener-lib

procedure
(place-tcp-listener? v) → boolean?
v : any/c

Returns #t when v is a listener returned by place-tcp-listen.

procedure
(place-tcp-listen start-place
port
[ #:boot-timeout boot-timeout
#:parallelism parallelism
#:hostname hostname
#:backlog backlog
#:reuse? reuse?
#:tcp@ tcp@])
→ place-tcp-listener?
  start-place : (-> place-channel?)
  port : listen-port-number?
  boot-timeout : (and/c positive? real?) = 60
  parallelism : exact-positive-integer? = (processor-count)
  hostname : (or/c #f string?) = #f
  backlog : exact-nonnegative-integer? = (* parallelism 4096)
  reuse? : boolean? = #f
  tcp@ : (unit/c (import) (export tcp^)) = racket/tcp

Starts a new TCP listener bound to port on the interface(s) identified by hostname. The listener starts new places by applying start-place. It then sends the places any new connections that it accepts, in round-robin order. The places started by start-place are expected to implement a specific protocol, therefore they must call start-place-tcp-receiver on boot and pass it the place channel.

The #:parallelism argument controls the number of places started by the listener.

The #:boot-timeout argument determines how long the listener waits for the places it starts to finish booting. If all the places fail to boot within the allotted time, an exception is raised.

The #:backlog and #:reuse? arguments have the same meaning as the max-allow-wait and reuse? arguments to tcp-listen, respectively.

The #:tcp@ argument can be used to provide a different underlying tcp^ implementation (eg. make-ssl-tcp@).

For example:

(define (start-echo-place)
  (place ch
    (define-values (p pid host port-no tcp@ receiver-dead-evt)
      (start-place-tcp-receiver ch))
    (define-values/invoke-unit
      tcp@
      (import)
      (export tcp^))
    (define listener
      (tcp-listen port-no 4096 #t host))
    (let loop ()
      (sync
       (handle-evt
        receiver-dead-evt
        (lambda (_)
          (tcp-close listener)))
       (handle-evt
        listener
        (lambda (_)
          (define-values (in out)
            (tcp-accept listener))
          (echo in out)
          (loop)))))))

(module+ main
  (define listener
    (place-tcp-listen start-echo-place 8000))
  (with-handlers ([exn:break? void])
    (sync/enable-break (place-tcp-listener-dead-evt listener)))
  (place-tcp-listener-stop listener))

procedure
(place-tcp-listener-addresses l) →
string? (integer-in 1 65535)
l : place-tcp-listener?

Returns the address of the interface the listener is listening on and the port it’s bound to.

procedure
(place-tcp-listener-dead-evt l) → evt?
l : place-tcp-listener?

Returns a synchronizable event that becomes ready for synchronization when the listener has stopped.

procedure
(place-tcp-listener-stop l) → void?
l : place-tcp-listener?

Stops the place TCP listener l.

procedure
(start-place-tcp-receiver place-channel)
→
exact-positive-integer?
exact-nonnegative-integer?
(or/c #f string?)
listen-port-number?
(unit/c (import) (export tcp^))
evt?
place-channel : place-channel?

Starts a background thread that implements the place communication protocol expected by place-tcp-listen and returns six values:

A positive integer, p, representing the number of receiver places.
An integer representing the place’s unique id in the range [0, p).
The hostname passed to place-tcp-listen in the main place.
The port number passed to place-tcp-listen in the main place.
A tcp^ unit that can be used to accept new connections from the main place.
An event that becomes ready for synchronization when the main place listener has been stopped.