Skip to contents

Queues and Services HTTP Requests

Source: R/webqueue.r
WebQueue.Rd

Connects the httpuv and jobqueue R packages.

Usage

webqueue(
  handler,
  host = "0.0.0.0",
  port = 8080L,
  parse = NULL,
  globals = list(),
  packages = NULL,
  namespace = 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. Return value is used as req going forward.

globals

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

packages

Character vector of package names to load on workers.

namespace

The name of a package to attach to the worker's environment.

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 and namespace. 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 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.

Value

A webqueue object with the following methods:

  • $url

    • Returns the URL where the server is available.

  • $stop(reason = 'server stopped')

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

    • reason - A brief message for the condition object.

    • Returns this webqueue, invisibly.

Examples

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