Creates a new Listener and binds it to a Socket.

listen(
  socket,
  url = "inproc://nanonext",
  tls = NULL,
  autostart = TRUE,
  error = FALSE
)

Arguments

socket

a Socket.

url

[default 'inproc://nanonext'] a URL to dial, specifying the transport and address as a character string e.g. 'inproc://anyvalue' or 'tcp://127.0.0.1:5555' (see transports).

tls

[default NULL] for secure tls+tcp:// or wss:// connections only, provide a TLS configuration object created by tls_config.

autostart

[default TRUE] whether to start the listener. Set to FALSE if setting configuration options on the listener as it is not generally possible to change these once started.

error

[default FALSE] behaviour on error: if FALSE, returns an integer exit code accompanied by a warning, or, if TRUE, generates an error and halts execution.

Value

Invisibly, an integer exit code (zero on success). A new Listener (object of class 'nanoListener' and 'nano') is created and bound to the Socket if successful.

Details

To view all Listeners bound to a socket use $listener on the socket, which returns a list of Listener objects. To access any individual Listener (e.g. to set options on it), index into the list e.g. $listener[[1]] to return the first Listener.

A listener is an external pointer to a listener object, which accepts incoming connections. A given listener object may have many connections at the same time, much like an HTTP server can have many connections to multiple clients simultaneously.

Further details

Dialers and Listeners are always associated with a single socket. A given socket may have multiple Listeners and/or multiple Dialers.

The client/server relationship described by dialer/listener is completely orthogonal to any similar relationship in the protocols. For example, a rep socket may use a dialer to connect to a listener on an req socket. This orthogonality can lead to innovative solutions to otherwise challenging communications problems.

Any configuration options on the dialer/listener should be set by opt<- before starting the dialer/listener with start.

Dialers/Listeners may be destroyed by close. They are also closed when their associated socket is closed.

Examples

socket <- socket("req")
listen(socket, url = "tcp://127.0.0.1:6547", autostart = FALSE)
socket$listener
#> [[1]]
#> < nanoListener >
#>  - id: 6
#>  - socket: 12
#>  - state: not started
#>  - url: tcp://127.0.0.1:6547
#> 
start(socket$listener[[1]])
socket$listener
#> [[1]]
#> < nanoListener >
#>  - id: 6
#>  - socket: 12
#>  - state: started
#>  - url: tcp://127.0.0.1:6547
#> 
close(socket$listener[[1]])
close(socket)

nano <- nano("bus")
nano$listen(url = "tcp://127.0.0.1:6548", autostart = FALSE)
nano$listener
#> [[1]]
#> < nanoListener >
#>  - id: 7
#>  - socket: 13
#>  - state: not started
#>  - url: tcp://127.0.0.1:6548
#> 
nano$listener_start()
nano$listener
#> [[1]]
#> < nanoListener >
#>  - id: 7
#>  - socket: 13
#>  - state: started
#>  - url: tcp://127.0.0.1:6548
#> 
close(nano$listener[[1]])
nano$close()