Open  CPU
1 Implementing New Types of Servers
2 Contracts
any/  r
number/  r
list/  r
hash/  r
list-no-duplicates/  c
r-package-can-add-functions/  c
dataframe-entry/  c
3 Exceptions
exn:  fail:  opencpu
exn:  fail:  opencpu:  server
exn:  fail:  opencpu:  r
exn:  fail:  network:  opencpu
exn:  fail:  network:  errno:  opencpu


Philip McGrath <philip at philipmcgrath dot com>

 (require opencpu) package: opencpu

This library provides an interface to the OpenCPU API, allowing programmers to call R functions from Racket over HTTP. Currently, the focus is on support for the stateless JSON RPC usage mode.

A major goal of the library is to abstract away the construction of API URLs, allowing different servers to be used interchangably — even servers that do not perform any HTTP requests at all — through the current-opencpu-server parameter. This is achieved by specifying R functions in terms of R packages.


(struct r-package (name guard))

  name : string?
  guard : (-> any/c)


(r-package name [guard])  r-package?

  name : string?
  guard : (-> any/c) = (λ () #t)

match expander

(r-package name-pat guard-pat)

(r-package name-pat)
Specifies an R package named name which corresponds to the entities implementing the OpenCPU R package API. Whether a package is global or user-specific is a property of the server, not of the package specification: the same package may be global on one server and user-specific on another. For this reason, r-package values are only equal? when they are eq?.

If the optional guard argument is provided to the constructor, R functions can only be added to the package when guard returns a non-false result. See also r-package-can-add-functions/c.


(define-r-function id pkg maybe-name-str
  option ...)
maybe-name-str = 
  | name-str
option = #:arg/c arg/c-expr
  | #:result/c result/c-expr
  pkg : r-package-can-add-functions/c
  name-str : string?
  arg/c-expr : flat-contract?
  result/c-expr : flat-contract?


(make-r-function pkg 
  [#:arg/c arg/c 
  #:result/c result/c]) 
(and/c r-function?
       (->* {arg/c}
            #:pre (send (current-opencpu-server) accept-package? pkg)
  pkg : r-package-can-add-functions/c
  name : string?
  arg/c : flat-contract? = (or/c list/r hash/r)
  result/c : flat-contract? = any/r
Both the function make-r-function and the special form define-r-function specify a new R function assosciated with the R package pkg: the difference is that R functions created using define-r-function report contract violations in terms of id and the string naming the function is inferred from id unless name-str is provided.

An R function is a procedure of a single argument, which must be either a list (for by-position arguments to a function) or a hash table (for functions with named arguments) and must satisfy the contract arg/c. Calling the function sends a request to the server determined by current-opencpu-server, which must support the function’s R package, and returns its result, which must satisfy the contract result/c. (Specifically, it uses the server’s call method.)

For low-level details on the representation of R functions, see r-function.

Specifies the server to be used for calls to R functions. A server will usually perform an HTTP request to some OpenCPU server, but may implement its functionality in arbitrary ways: for example, no-opencpu-server is a server which doesn’t allow any R functions to be run.


(make-opencpu-server u 
  [#:packages pkgs 
  #:users users]) 
  (is-a?/c remote-opencpu-server<%>)
  u : 
(struct/dc url
           [scheme string?]
           [host string?])
  pkgs : 
(or/c #f (and/c (listof r-package?)
 = #f
  users : (and/c (listof r-user?) list-no-duplicates/c) = '()
Creates a server that implements R functions by performing HTTP requests to the OpenCPU server with base url u.

Any R package included in an r-user value in users is treated as local to that user.

If pkgs is #f, all other R packages are supported and are assumed to be installed globally. If pkgs is a list of R packages, only the listed packages are supported as global packages.

A given R package may appear at most once, either in the pkgs or the users argument to make-opencpu-server.

Used to tag servers creaded by make-opencpu-server.


(struct r-user (name packages))

  name : string?
  packages : (and/c (listof r-package?) list-no-duplicates/c)
Used with make-opencpu-server to define R packages installed locally to a particular user.

A server that uses the public OpenCPU server at to implement R functions.

A server which doesn’t allow any R functions to be run.


(make-caching-opencpu-server inner-server)

  (is-a?/c opencpu-server<%>)
  inner-server : (is-a?/c opencpu-server<%>)
Creates a server that behaves like inner-server, but which caches the results of R functions to avoid consulting inner-server on duplicate calls.

1 Implementing New Types of Servers

Any object that implements opencpu-server<%> may be used as a server, allowing R functions to be implemented in arbitrary ways.


(send an-opencpu-server accept-package? pkg)  any/c

  pkg : r-package?
Should return #f to indicate that the R package pkg is not supported by an-opencpu-server, in which case the contract on call will prevent any R functions assosciated with pkg from being run. For example, (send no-opencpu-server accept-package? some-package) always returns #f.


(send an-opencpu-server call fn arg)  (r-function-result/c fn)

  fn : 
(and/c r-function?
       (λ (fn)
         (send an-opencpu-server
               (r-function-package fn))))
  arg : 
(and/c (or/c list/r hash/r)
       (r-function-arg/c fn))
Tells an-opencpu-server to execute its implementation of the R function fn using the argument arg. The implementation may perform an HTTP request to an OpenCPU server (as servers created by make-opencpu-server do), but alternatively may produce the result in any arbitrary way (e.g. by consulting a cache).


(struct r-function (package name arg/c result/c))

  package : r-package?
  name : string?
  arg/c : flat-contract?
  result/c : flat-contract?
The low-level representation of R functions, which may be useful when implementing call. Note that the constructor is not provided: instead, use define-r-function or make-r-function.

2 Contracts


any/r : flat-contract?

(or/c boolean?


number/r : flat-contract? = (or/c exact-integer? inexact-real?)


list/r : flat-contract? = (listof any/r)


hash/r : flat-contract?

(and/c (hash/c symbol? any/r
               #:immutable #t)
Contracts recognizing the types of values that can be accepted and produced by R functions

Reconizes lists that do not contain any duplicate entries (according to equal?).

Recognizes R packages for which the r-package-guard would permit R functions to be added when the contract is checked.


(dataframe-entry/c [key-id . contract-expr] ...)

  contract-expr : flat-contract?
Creates a flat contract accepting immutable, eq?-based hash-tables consisting of exactly the symbolic form of each key-id as keys (i.e. hashes with missing or extra keys will be rejected), where each corresponding value must satisfy (and/c contract-expr any/r). Thus, the resulting contract is more strict than hash/r.

These contracts may be used in any context, but are particularly useful in writing contracts for R "data frame" values, which are represented as a list of hash tables conforming to the same dataframe-entry/c contract, where each key-id is translated as the heading of "column" of the dataframe.

3 Exceptions

This section documents exceptions that may be raised by this library. Note that none of the constructors for structures documented in this section are provided.


(opencpu-error? v)  any/c

  v : any/c
A predicate recognizing the exceptions documented in this section.


(struct exn:fail:opencpu exn:fail (status))

  status : bytes?
The supertype for errors resulting from the OpenCPU HTTP server (except contract violations, for which exn:fail:contract is used). Direct instances of this type are currently only created if the HTTP response has an unknown status code.

Represents an error in the OpenCPU HTTP server, which is indicated by an HTTP status code of 502 or 503.


(struct exn:fail:opencpu:r exn:fail:opencpu (r-error-message))

  r-error-message : string?
Indicates that R encountered an error, which is indicated by an HTTP status code of 400. The exn:fail:opencpu:r-r-error-message (which is also included in the exn-message) is the error message from R.


(opencpu-network-error? v)  any/c

  v : any/c


(opencpu-network-error-orig-message e)  string?

  e : opencpu-network-error?


(opencpu-network-error-orig-marks e)  continuation-mark-set?

  e : opencpu-network-error?


(struct exn:fail:network:opencpu exn:fail:network (orig-message
  orig-message : string?
  orig-marks : continuation-mark-set?


(struct exn:fail:network:errno:opencpu exn:fail:network:errno
  orig-message : string?
  orig-marks : continuation-mark-set?
When this library encounters an exn:fail:network or an exn:fail:network:errno, it re-raises the exception with an OpenCPU-specific subtype. The message and continuation marks from the underlying exception are preserved and can be accessed with the generic functions opencpu-network-error-orig-message and opencpu-network-error-orig-marks, respectively.