Tell the object checkpointer how to capture an object

gptr_preimage() is the S3 generic the object checkpointer calls for a binding of the workspace before a tool call that runs R code. It decides how the value the binding holds now is kept, so that a rewind can put it back. Methods are leaf functions: they may read x but must never store it anywhere.

Usage

gptr_preimage(x, name, ctx, ...)

# Default S3 method
gptr_preimage(x, name, ctx, ...)

# S3 method for class 'data.table'
gptr_preimage(x, name, ctx, ...)

Arguments

x: The object bound to name.
name: The binding name (a string).
ctx: A list: predicted, what the agent's code is predicted to do to name ("assign", "modify", "byref", "remove" or "none"); bytes, the size of x in bytes (NA when unknown); budget, the largest copy allowed, in bytes. When ctx$dry is TRUE the checkpointer only asks whether a capture is possible and a method must not copy.
...: Unused; for methods.

Value

A list with mode ("ref", "copy" or "none"), reason (a string explaining "none", else NULL) and copy (the deep copy for "copy", else NULL).

Details

The default method keeps value-semantics objects by reference ("ref": nothing is copied unless the agent edits the object in place) and reports environments (including R6 and RefClass objects) and external pointers as not restorable ("none"). The data.table method returns a deep copy made with data.table::copy() ("copy") when the agent's code is predicted to modify the table by reference (:=, set*()) and the table fits the budget. Packages add methods for their own classes with a delayed registration, S3method(gptr::gptr_preimage, myclass); an R6 class can, for example, return x$clone(deep = TRUE) as "copy". This generic is experimental.

Examples

gptr_preimage(1:3, "x", list(predicted = "assign", bytes = 64, budget = 1e9))$mode
#> [1] "ref"
gptr_preimage(new.env(), "cfg", list(predicted = "modify", bytes = NA, budget = 1e9))$reason
#> [1] "reference object (environment, R6 or external pointer)"