Package delay provides a way to execute code outside the scope of a user request by using the taskqueue API.
To declare a function that may be executed later, call Func in a top-level assignment context, passing it an arbitrary string key and a function whose first argument is of type context.Context. The key is used to look up the function so it can be called later.
var laterFunc = delay.Func("key", myFunc)
It is also possible to use a function literal.
var laterFunc = delay.Func("key", func(c context.Context, x string) { // ... })
To call a function, invoke its Call method.
laterFunc.Call(c, "something")
A function may be called any number of times. If the function has any return arguments, and the last one is of type error, the function may return a non-nil error to signal that the function should be retried.
The arguments to functions may be of any type that is encodable by the gob package. If an argument is of interface type, it is the client's responsibility to register with the gob package whatever concrete type may be passed for that argument; see http://golang.org/pkg/gob/#Register for details.
Any errors during initialization or execution of a function will be logged to the application logs. Error logs that occur during initialization will be associated with the request that invoked the Call method.
The state of a function invocation that has not yet successfully executed is preserved by combining the file name in which it is declared with the string key that was passed to the Func function. Updating an app with pending function invocations should safe as long as the relevant functions have the (filename, key) combination preserved. The filename is parsed according to these rules:
- Paths in package main are shortened to just the file name (github.com/foo/foo.go -> foo.go)
- Paths are stripped to just package paths (/go/src/github.com/foo/bar.go -> github.com/foo/bar.go)
- Module versions are stripped (/go/pkg/mod/github.com/foo/bar@v0.0.0-20181026220418-f595d03440dc/baz.go -> github.com/foo/bar/baz.go)
There is some inherent risk of pending function invocations being lost during an update that contains large changes. For example, switching from using GOPATH to go.mod is a large change that may inadvertently cause file paths to change.
The delay package uses the Task Queue API to create tasks that call the reserved application path "/_ah/queue/go/delay". This path must not be marked as "login: required" in app.yaml; it must be marked as "login: admin" or have no access restriction.
Functions
func RequestHeaders
func RequestHeaders(c context.Context) (*taskqueue.RequestHeaders, error)RequestHeaders returns the special task-queue HTTP request headers for the current task queue handler. Returns an error if called from outside a delay.Func.
Function
type Function struct {
// contains filtered or unexported fields
}Function represents a function that may have a delayed invocation.
func Func
Func declares a new Function. The second argument must be a function with a first argument of type context.Context. This function must be called at program initialization time. That means it must be called in a global variable declaration or from an init function. This restriction is necessary because the instance that delays a function call may not be the one that executes it. Only the code executed at program initialization time is guaranteed to have been run by an instance before it receives a request.
func (*Function) Call
Call invokes a delayed function.
err := f.Call(c, ...)
is equivalent to
t, _ := f.Task(...)
_, err := taskqueue.Add(c, t, "")
func (*Function) Task
Task creates a Task that will invoke the function. Its parameters may be tweaked before adding it to a queue. Users should not modify the Path or Payload fields of the returned Task.