Skip to contents

Queues and Services HTTP Requests

Source: R/webqueue.r
WebQueue.Rd

Connects the 'httpuv' and 'jobqueue' R packages.

Active bindings

url

URL where the server is available.

Methods

Public methods

Method new()

Creates an httpuv::WebServer with requests handled by a jobqueue::Queue.

Usage

WebQueue$new(
  handler,
  host = "0.0.0.0",
  port = 8080L,
  parse = NULL,
  globals = list(),
  packages = NULL,
  init = NULL,
  max_cpus = availableCores(),
  workers = ceiling(max_cpus * 1.2),
  timeout = NULL,
  hooks = NULL,
  reformat = NULL,
  stop_id = NULL,
  copy_id = NULL,
  bg = TRUE,
  quiet = FALSE,
  onHeaders = NULL,
  staticPaths = NULL,
  staticPathOptions = NULL
)

Arguments

handler

A function (request) that will be run on a background worker process. The returned value will be passed through reformat, then sent as the server's response to the web client.

host

A string that is a valid IPv4 address that is owned by this server, or '0.0.0.0' to listen on all IP addresses.

port

A number or integer that indicates the server port that should be listened on. Note that on most Unix-like systems including Linux and macOS, port numbers smaller than 1024 require root privileges.

parse

A function (req) that is run on the foreground process to transform the HTTP request prior to passing it to handler. req is the environment object provided by 'httpuv', amended with $ARGS and $COOKIES. Edit req in place and/or signal an error.

globals

A list of variables to add to handler's evaluation environment.

packages

Character vector of package names to load on workers.

init

A call or R expression wrapped in curly braces to evaluate on each worker just once, immediately after start-up. Will have access to variables defined by globals and assets from packages. Returned value is ignored.

max_cpus

Total number of CPU cores that can be reserved by all running Jobs (sum(cpus)). Does not enforce limits on actual CPU utilization.

workers

How many background jobqueue::Worker processes to start. Set to more than max_cpus to enable interrupted workers to be quickly swapped out with standby Workers while a replacement Worker boots up.

timeout

A named numeric vector indicating the maximum number of seconds allowed for each state the job passes through, or 'total' to apply a single timeout from 'submitted' to 'done'. Example: timeout = c(total = 2.5, running = 1).

hooks

A list of functions to run when the Job state changes, of the form hooks = list(created = function (job) {...}, done = ~{...}). See vignette('hooks').

reformat

A function (job) that is run in the foreground process to transform the output from handler. The default, reformat = NULL, is essentially function (job) { job$output }.

stop_id

A function (job). If two Jobs generate the same value from this function, then the earlier Job will be aborted. If the returned value is NULL, no Jobs will be stopped.

copy_id

A function (job). If two Jobs generate the same value from this function, then the later Job will clone its output from the earlier Job. If the returned value is NULL, no Jobs will be cloned.

bg

Where/how to run the server. TRUE: on a separate R process. FALSE: blocking on the current R process. NULL: non-blocking on the current R process.

quiet

If TRUE, suppress error messages from starting the 'httpuv' server.

onHeaders

A function (request) triggered when headers are received by 'httpuv'. Return NULL to continue normal processing of the request, or a Rook response to send that response, stop processing the request, and ask the client to close the connection. (This can be used to implement upload size limits, for example.)

staticPaths

A named list of paths that will be served without invoking handler() or onHeaders(). The name of each one is the URL path, and the value is either a string referring to a local path, or an object created by the httpuv::staticPath() function.

staticPathOptions

A set of default options to use when serving static paths. If not set or NULL, then it will use the result from calling httpuv::staticPathOptions() with no arguments.

Returns

A WebQueue object.

Method print()

Print method for a WebQueue.

Usage

WebQueue$print(...)

Arguments

...

Arguments are not used currently.

Method stop()

Shuts down the WebQueue and all associated subprocesses. Stopped Jobs will have their $output set to a object of class <interrupt/condition>

Usage

WebQueue$stop(reason = "server stopped")

Arguments

reason

A brief message for the condition object.

Returns

This WebQueue, invisibly.

Examples

    
    library(webqueue)
    
    wq <- WebQueue$new(function (req) 'Hello World!\n')
    readLines(wq$url)
#> [1] "Hello World!"
    wq$stop()