On this page:
3.1 Socket
socket?
socket
close-socket
socket-closed?
null-socket
byte-socket
string-socket
file-socket
3.2 Codec
parser/  c
printer/  c
codec/  c
flushed
decoder
encoder
codec
3.2.1 Codec Types
make-codec-type
define-codec
line-parser
line-printer
line-decoder
line-encoder
line-codec
sexp-parser
sexp-printer
sexp-decoder
sexp-encoder
sexp-codec
json-parser
json-printer
json-decoder
json-encoder
json-codec
3.3 Network
3.3.1 TCP
tcp-socket?
tcp-socket
tcp-socket-address
tcp-client
tcp-server
tcp-service

3 Data Flow🔗ℹ

3.1 Socket🔗ℹ

 (require neuron/socket) package: neuron-lib

A socket is the local end of a bi-directional serial communications channel. Each socket holds an input port and an output port.

A socket can be used as a synchronizable event. A socket is ready for synchronization when the ports it holds have closed. Sockets do not support half-open connections—when either port closes, the other port is closed immediately.

procedure

(socket? v)  boolean?

  v : any/c
Returns #t if v is a socket, #f otherwise.

procedure

(socket in-port out-port)  socket?

  in-port : input-port?
  out-port : output-port?
Returns a socket. Serves as out-port when used as an output port, and as in-port when used as an input port or with procedures that take both kinds, such as file-position.

procedure

(close-socket sock)  void?

  sock : socket?
Closes the ports held by sock. If the ports are already closed, close-socket has no effect.

procedure

(socket-closed? sock)  boolean?

  sock : socket?
Returns "#t" if the ports held by sock are closed, #f otherwise.

procedure

(null-socket)  socket?

Returns a socket that ignores all input and always outputs eof.

procedure

(byte-socket [#:in str #:out out?])  socket?

  str : bytes? = #""
  out? : boolean? = #f

procedure

(string-socket [#:in str #:out out?])  socket?

  str : string? = ""
  out? : boolean? = #f
Returns a socket that inputs from str and, if out? is #t, accumulates output in a fresh output string port.

Example:
> (define sock (string-socket #:in "123" #:out #t))
> (read sock)

123

> (write 'abc sock)
> (get-output-string sock)

"abc"

procedure

(file-socket [#:in in-path    
  #:in-mode in-mode-flag    
  #:out out-path    
  #:out-mode out-mode-flag]    
  #:exists exists-flag)  socket?
  in-path : (or/c path-string? #f) = #f
  in-mode-flag : (or/c 'binary 'text) = 'binary
  out-path : (or/c path-string? #f) = #f
  out-mode-flag : (or/c 'binary 'text) = 'binary
  exists-flag : 
(or/c 'error 'append 'update 'can-update
      'replace 'truncate
      'must-truncate 'truncate/replace)
Returns a socket that opens the files specified by in-path and out-path for input and output, respectively. If in-path is #f, then all input is ignored. If out-path is #f, then only eof is output. If both are #f, then the file-socket call is equivalent to (null-socket).

See open-input-file for details on in-mode-flag, and open-output-file for details on out-mode-flag and exists-flag.

3.2 Codec🔗ℹ

 (require neuron/codec) package: neuron-lib

A codec is a stream that uses a socket to exchange serializable values with remote agents. The sink is called an encoder; it uses a printer procedure to serialize values to a socket. The source is called a decoder; it uses a parser procedure to de-serialize values from a socket.

value

parser/c : contract? = (-> socket? any/c)

Use this function contract to indicate that a function is a parser.

Use this function contract to indicate that a function is a printer.

Use this function contract to indicate that a function makes decoders, encoders, or codecs.

procedure

(flushed prn)  printer/c

  prn : printer/c
Returns a printer that applies prn to a socket and then flushes its output port.

procedure

(decoder prs)  codec/c

  prs : parser/c
Returns a procedure that makes decoders based on prs:

Parses and emits values from a socket. Stops when prs returns eof. Closes the socket when it stops. Dies when the socket closes.

Commands:

Example:
> (define dec ((decoder read) (string-socket #:in "123 abc")))
> (recv dec)

123

> (recv dec)

'abc

> (recv dec)

#<eof>

procedure

(encoder prn)  codec/c

  prn : printer/c
Returns a procedure that makes encoders based on prn:

Takes and prints values to a socket. Stops when it takes eof. Closes the socket when it stops. Dies when the socket closes.

Commands:

Example:
> (define enc ((encoder writeln) (string-socket #:out #t)))
> (for-each (curry give enc) (list 123 'abc eof))
> (get-output-string (enc 'socket))

"123\nabc\n"

procedure

(codec prs prn)  codec/c

  prs : parser/c
  prn : printer/c
Returns a procedure that makes codecs based on prs and prn:

Takes and prints values to a socket. Reads and emits values from a socket. Stops when given eof or prs returns eof. Closes the socket when it stops. Dies when the socket closes.

Commands:

Example:
> (define cdc ((codec read writeln)
               (string-socket #:in "123 abc" #:out #t)))
> (for-each (curry give cdc) (list 987 'zyx eof))
> (recv cdc)

123

> (recv cdc)

'abc

> (recv cdc)

#<eof>

> (get-output-string (cdc 'socket))

"987\nzyx\n"

3.2.1 Codec Types🔗ℹ

A codec type is a set of uniformly-named procedures for making codecs and codec parts. A complete codec type named name is defined by the following procedures:

procedure

(make-codec-type name prs prn)  
codec/c codec/c codec/c
  name : symbol?
  prs : parser/c
  prn : printer/c
Creates a new codec type. The name argument is used as the type name.

The result of make-codec-type is three values:

syntax

(define-codec name prs prn)

Creates a new codec type and binds variables related to the codec type.

A define-codec form defines 5 names:

procedure

line-parser : parser/c

procedure

line-printer : printer/c

procedure

line-decoder : codec/c

procedure

line-encoder : codec/c

procedure

line-codec : codec/c

Example:
> (define cdc
    (line-codec
      (string-socket #:in "123 abc\n" #:out #t)))
> (give cdc "987 zyx")

#t

> (recv cdc)

"123 abc"

> (get-output-string (cdc 'socket))

"987 zyx\n"

procedure

sexp-parser : parser/c

procedure

sexp-printer : printer/c

procedure

sexp-decoder : codec/c

procedure

sexp-encoder : codec/c

procedure

sexp-codec : codec/c

S-expression codec type.

Example:
> (define cdc
    (sexp-codec
      (string-socket #:in "(#hasheq((ab . 12)) 34)" #:out #t)))
> (give cdc (list 987 'zyx))

#t

> (recv cdc)

'(       #hasheq((ab . 12))34)

> (get-output-string (cdc 'socket))

"(987 zyx)\n"

procedure

json-parser : parser/c

procedure

json-printer : printer/c

procedure

json-decoder : codec/c

procedure

json-encoder : codec/c

procedure

json-codec : codec/c

To change how null is represented, set the json-null parameter in the JSON library.

Example:
> (require json)
> (define cdc
    (parameterize ([json-null 'NULL])
      (json-codec
        (string-socket #:in "[{\"ab\":12},34,null]" #:out #t))))
> (give cdc '(98 #hasheq((zy . 76)) NULL))

#t

> (recv cdc)

'(       #hasheq((ab . 12))34 NULL)

> (get-output-string (cdc 'socket))

"[98,{\"zy\":76},null]\n"

3.3 Network🔗ℹ
3.3.1 TCP🔗ℹ

 (require neuron/network/tcp) package: neuron-lib

A TCP socket is a socket with a TCP address.

procedure

(tcp-socket? v)  boolean?

  v : any/c
Returns #t if v is a TCP socket, #f otherwise.

procedure

(tcp-socket in-port out-port)  tcp-socket?

  in-port : input-port?
  out-port : output-port?
Returns a TCP socket.

procedure

(tcp-socket-address sock)  
(list/c string? port-number?
        string? port-number?)
  sock : tcp-socket?
Returns the address of TCP socket sock.

procedure

(tcp-client hostname    
  port-no    
  [local-hostname    
  local-port-no])  socket?
  hostname : string?
  port-no : port-number?
  local-hostname : (or/c string? #f) = #f
  local-port-no : (or/c port-number? #f) = #f
Establishes a TCP connection to hostname:port-no. Returns a TCP socket.

See tcp-connect for argument details.

procedure

(tcp-server port-no    
  [max-allow-wait    
  reuse?    
  hostname])  process?
  port-no : listen-port-number?
  max-allow-wait : exact-nonnegative-integer? = 4
  reuse? : any/c = #f
  hostname : (or/c string? #f) = #f
Creates a “listening” TCP server on hostname:port-no. Returns a source that emits a TCP socket for each connection accepted.

See tcp-listen for argument details.

Commands:

procedure

(tcp-service make-codec    
  srv    
  [#:on-accept on-accept    
  #:on-drop on-drop])  process?
  make-codec : codec/c
  srv : process?
  on-accept : (-> any/c process? any) = void
  on-drop : (-> any/c process? any) = void
Returns a service keyed by TCP socket address. Applies make-codec to each TCP socket emitted by srv and adds the resulting codec to the service. When given (list addr v), forwards v to addr. Emits (list addr v) when addr emits v. Applies on-accept to the codecs made by make-codec and their addresses. Applies on-drop to each address–codec pair it drops. Drops each codec that dies. Drops every codec when it stops.

Commands: