V1 SDK Method Naming

[mrkaye97]

Hi everyone! We're looking for some feedback on method naming in the V1 SDKs. We're planning to have two different ways of running workflows:

1. Run a workflow without waiting for the result to come back (equivalent to the current run_workflow implementation where the method returns a WorkflowRunRef
2. Run a workflow and wait for the result to come back, equivalent to getting the WorkflowRunRef and then calling result() on it.

We're thinking of some options for how to name these two methods, and would love feedback. Leaving some options below.

If you have other ideas, feel free to leave them as a comment and we'll add them to the poll!

[aejimmi]

"enqueue" in dev UX sucks though correct meaning . "run*" is obvious

[knksmith57]

Do you have any reference data (or even qualitative signal) on the relative popularity of each usage pattern?

Are most folks “fire and forget” or “invoke and wait”?

We’re heavy users of event triggers, so our workflows are almost entirely “fire and forget” on the caller/writer side with many different consumers “collecting” by subscribing via additional metadata on the reader side. We might be outliers.

Naming is hard, but I like how the anyio folks use a _nowait suffix when enqueuing to indicate that the caller should not block until a consumer starts dequeuing.

In Hatchet land, that might translate to, e.g.: run and run_nowait or invoke and invoke_nowait.

If instead we actually are the common case, the inverse also works, e.g.: run and run_wait.

Finally, y’all could decide to make both behaviors explicit, e.g.: run_wait and run_nowait.