Additional docs for runoncreate option

[nmstone]

Is your feature request related to a problem? Please describe.
Jobs created with runoncreate seem to both create and execute the job as part of the request and do not return a response until the job execution has completed. Jobs created without runoncreate respond immediately after the job has been created.

Describe the solution you'd like
Docs should be clear about the execution difference between runoncreate and normal jobs (runoncreate = blocking job execution (job creation + job execution) VS. no runoncreate = "asynchronous" job execution (job creation only, execution happens later)). OR runoncreate should operate asynchronously and return once the job has been created and execute the job in the background, just like adding a scheduled job.

Describe alternatives you've considered
Seems like adding a job and executing immediately without the REST request hanging while the job executes can be done by creating the job as disabled and enabling/running it after creation, however this requires multiple requests, and my initial assumption was that runoncreate would replicate this behavior. I have used other schedulers that treat a "run immediately" job exactly the same as a scheduled job which is where my confusion came from.

Appreciate the project! I just had the wrong assumption that runoncreate jobs would return the job object and execute the job in the background rather than blocking until execution completed. Took me a while to figure this out so hope it helps someone.

[yvanoers]

Seems like adding a job and executing immediately without the REST request hanging while the job executes can be done by creating the job as disabled and enabling/running it after creation, however this requires multiple requests, and my initial assumption was that runoncreate would replicate this behavior.

It does replicate this behavior.
The REST API call used to run a job after creating it, also waits for the job to complete.

I agree that it is reasonable to expect a job to only be triggered by the API. I am reluctant to make this the default behavior, because people may depend on it. But what about a second request parameter, like async=1, to make it fire & forget?
The docs should be updated anyhow, sure.

[nmstone]

Ah I see now that the current approach makes sense as the default behavior. I gave it a try and see what you mean, run job does indeed wait. I just had the wrong assumption going in.

async=1 would be really nice as a second parameter (or even async=1 for triggering a job via /jobs/{job_name}) but just a short doc note would be good too! If this issue had existed while I was researching I would have found it to be useful so wanted to create as pseudo documentation for others.

[yvanoers]

PR #950 should clarify the run behavior.
I will hold off on adding an async parameter until @Victorcoder gives his blessing.