From 3e847e005717c50d7a09078e71c93a11a12a9949 Mon Sep 17 00:00:00 2001 From: Connor Hicks Date: Mon, 4 Jan 2021 20:37:25 -0500 Subject: [PATCH] update docs --- README.md | 14 +++++++------- docs/getstarted.md | 18 +++++++++--------- docs/grav.md | 4 ++-- docs/wasm.md | 2 +- hive/job.go | 11 ----------- 5 files changed, 19 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 5623dbee..21b30af5 100644 --- a/README.md +++ b/README.md @@ -6,13 +6,13 @@ Hive is a fast, performant job scheduling system, plain and simple. Hive is desi Hive transparently spawns workers to process jobs, with each worker processing jobs in sequence. Hive jobs are arbitrary data, and they return arbitrary data (or an error). Jobs are scheduled by clients, and their results can be retreived at a later time. -## FaaS +## WASM -Hive has early (read: alpha) support for acting as a Functions-as-a-Service system. Hive can be run as a server, accepting jobs from HTTP/S and making the job results available to be fetched later. See [faas](./docs/faas.md) for details. gRPC support is planned. +Hive has early (read: beta) support for Wasm-packaged runnables. This is actively being worked on, as Wasm is an exciting new standard that makes cross-language and cross-platform code just a bit easier :) See [wasm](./docs/wasm.md) and the [subo CLI](https://github.com/suborbital/subo) for details. -## WASM +## FaaS -Hive has early (read: alpha) support for Wasm-packaged runnables. This is actively being worked on, as Wasm is an exciting new standard that makes cross-language and cross-platform code just a bit easier :) See [wasm](./docs/wasm.md) and the [subo CLI](https://github.com/suborbital/subo) for details. +Hive has early (read: alpha) support for acting as a Functions-as-a-Service system. Hive can be run as a server, accepting jobs from HTTP/S and making the job results available to be fetched later. See [faas](./docs/faas.md) for details. gRPC support is planned. ### The Basics @@ -26,7 +26,7 @@ And then get started by defining something `Runnable`: type generic struct{} // Run runs a generic job -func (g generic) Run(job hive.Job, do hive.DoFunc) (interface{}, error) { +func (g generic) Run(job hive.Job, ctx *hive.Ctx) (interface{}, error) { fmt.Println("doing job:", job.String()) // get the string value of the job's data // do your work here @@ -34,8 +34,8 @@ func (g generic) Run(job hive.Job, do hive.DoFunc) (interface{}, error) { return fmt.Sprintf("finished %s", job.String()), nil } -// OnStart is called when Hive starts up a worker to handle jobs, -// and allows the Runnable to set itself up before receiving jobs +// OnChange is called when Hive starts or stops a worker to handle jobs, +// and allows the Runnable to set up before receiving jobs or tear down if needed. func (g generic) OnChange(change ChangeEvent) error { return nil } diff --git a/docs/getstarted.md b/docs/getstarted.md index daca7976..c6e6aaef 100644 --- a/docs/getstarted.md +++ b/docs/getstarted.md @@ -9,13 +9,13 @@ There are some more complicated things you can do with Runnables: type recursive struct{} // Run runs a recursive job -func (r recursive) Run(job hive.Job, do hive.DoFunc) (interface{}, error) { +func (r recursive) Run(job hive.Job, ctx *hive.Ctx) (interface{}, error) { fmt.Println("doing job:", job.String()) if job.String() == "first" { - return do(hive.NewJob("recursive", "second")), nil + return ctx.Do(hive.NewJob("recursive", "second")), nil } else if job.String() == "second" { - return do(hive.NewJob("recursive", "last")), nil + return ctx.Do(hive.NewJob("recursive", "last")), nil } return fmt.Sprintf("finished %s", job.String()), nil @@ -25,9 +25,9 @@ func (r recursive) OnChange(change ChangeEvent) error { return nil } ``` -The `hive.DoFunc` that you see there is a way for your Runnable to, well, run more things! +The `hive.Ctx` you see there is the job context, and one of the things it can do is run more things! -Calling the `DoFunc` will schedule another job to be executed and give you a `Result`. If you return a `Result` from `Run`, then the caller will recursively recieve that `Result` when they call `Then()`! +Calling `ctx.Do` will schedule another job to be executed and give you a `Result`. If you return a `Result` from `Run`, then the caller will recursively recieve that `Result` when they call `Then()`! For example: ```golang @@ -72,9 +72,9 @@ A hive `Group` is a set of `Result`s that belong together. If you're familiar wi ```golang grp := hive.NewGroup() -grp.Add(do(hive.NewJob("recursive", "first"))) -grp.Add(do(hive.NewJob("generic", "group work"))) -grp.Add(do(hive.NewJob("generic", "group work"))) +grp.Add(ctx.Do(hive.NewJob("recursive", "first"))) +grp.Add(ctx.Do(hive.NewJob("generic", "group work"))) +grp.Add(ctx.Do(hive.NewJob("generic", "group work"))) if err := grp.Wait(); err != nil { log.Fatal(err) @@ -140,7 +140,7 @@ type input struct { type math struct{} // Run runs a math job -func (g math) Run(job hive.Job, do hive.DoFunc) (interface{}, error) { +func (g math) Run(job hive.Job, ctx *hive.Ctx) (interface{}, error) { in := job.Data().(input) return in.First + in.Second, nil diff --git a/docs/grav.md b/docs/grav.md index f992834b..8cc9be03 100644 --- a/docs/grav.md +++ b/docs/grav.md @@ -10,8 +10,8 @@ g := grav.New() hive.HandleMsg(g.Connect(), msgTypeLogin, &loginEmailRunner{}) ``` -Whenever a message with the given type is received from the bus, a `Job` will be queued to be handled by the provided Runnable. The `Job` will contain the message, and `job.Msg()` makes it easy to retreive (with type conversions happening automatically). +Whenever a message with the given type is received from the bus, a `Job` will be queued to be handled by the provided Runnable. The `Job` will contain the message data. -The result returned by the Runnable's `Run` function may be a `grav.Message`. If so, it will be sent back out over the message bus. Anything else will be put into a mesage (by converting it to a byte array) and sent back over the bus. If `Run` returns an error a message with type `hive.joberr` will be sent. If `Run` returns `nil, nil`, then a message of type `hive.nil` will be sent. All messages sent will be a reply to the message that triggered the job. +The result returned by the Runnable's `Run` function may be a `grav.Message`. If so, it will be sent back out over the message bus. Anything else will be put into a mesage (by converting it into bytes) and sent back over the bus. If `Run` returns an error, a message with type `hive.joberr` will be sent. If `Run` returns `nil, nil`, then a message of type `hive.nil` will be sent. All messages sent will be a reply to the message that triggered the job. Further integrations with `Grav` are in the works, along with improvements to Hive's [FaaS](./faas.md) capabilities, which is powered by Suborbital's [Vektor](https://github.com/suborbital/vektor) framework. \ No newline at end of file diff --git a/docs/wasm.md b/docs/wasm.md index 66269ce4..239608f9 100644 --- a/docs/wasm.md +++ b/docs/wasm.md @@ -6,7 +6,7 @@ Wasm support in Hive is powered by [Wasmer](https://github.com/wasmerio/wasmer-g The `subo` CLI is also in its early days, so please bear with us! -The currently "supported" language is Rust, but that only means we are providing the boilerplate needed to use Rust/Wasm code. Any language that compiles to Wasm can be used if the functions in [lib.rs](https://github.com/suborbital/subo/blob/main/builders/rust/src/lib.rs) are re-created for that language. +The current supported languages are Rust and Swift, and the Runnable API is available for each. More languages such as AssemblyScript, Go, and C++ are coming soon! To create a Wasm runnable, check out the [subo CLI](https://github.com/suborbital/subo). Once you've generated a `.wasm` file, you can use it with Hive just like any other Runnable! diff --git a/hive/job.go b/hive/job.go index 5da8377d..857eb215 100644 --- a/hive/job.go +++ b/hive/job.go @@ -5,7 +5,6 @@ import ( "errors" "github.com/google/uuid" - "github.com/suborbital/grav/grav" ) // JobReference is a lightweight reference to a Job @@ -91,16 +90,6 @@ func (j Job) Data() interface{} { return j.data } -// Msg returns a grav.Message stored in the Job, if any -func (j Job) Msg() grav.Message { - msg, ok := j.data.(grav.Message) - if !ok { - return nil - } - - return msg -} - // loadResult has a pointer reciever such that it actually modifies the object it's being called on func (j *Job) loadResult(resultData interface{}, errString string) { j.resultData = resultData