1 files changed, 78 insertions, 0 deletions
diff --git a/src/nvim/os/job.h b/src/nvim/os/job.h
new file mode 100644
index 0000000000..db147f2c24
--- /dev/null
+++ b/src/nvim/os/job.h
@@ -0,0 +1,78 @@
+// Job is a short name we use to refer to child processes that run in parallel
+// with the editor, probably executing long-running tasks and sending updates
+// asynchronously. Communication happens through anonymous pipes connected to
+// the job's std{in,out,err}. They are more like bash/zsh co-processes than the
+// usual shell background job. The name 'Job' was chosen because it applies to
+// the concept while being significantly shorter.
+#ifndef NEOVIM_OS_JOB_H
+#define NEOVIM_OS_JOB_H
+
+#include <stdint.h>
+#include <stdbool.h>
+
+#include "os/event_defs.h"
+#include "os/rstream_defs.h"
+
+/// Initializes job control resources
+void job_init(void);
+
+/// Releases job control resources and terminates running jobs
+void job_teardown(void);
+
+/// Tries to start a new job.
+///
+/// @param argv Argument vector for the process. The first item is the
+///        executable to run.
+/// @param data Caller data that will be associated with the job
+/// @param stdout_cb Callback that will be invoked when data is available
+///        on stdout
+/// @param stderr_cb Callback that will be invoked when data is available
+///        on stderr
+/// @param exit_cb Callback that will be invoked when the job exits. This is
+///        optional.
+/// @return The job id if the job started successfully. If the the first item /
+///         of `argv`(the program) could not be executed, -1 will be returned.
+//          0 will be returned if the job table is full.
+int job_start(char **argv,
+              void *data,
+              rstream_cb stdout_cb,
+              rstream_cb stderr_cb,
+              job_exit_cb exit_cb);
+
+/// Terminates a job. This is a non-blocking operation, but if the job exists
+/// it's guaranteed to succeed(SIGKILL will eventually be sent)
+///
+/// @param id The job id
+/// @return true if the stop request was successfully sent, false if the job
+///              id is invalid(probably because it has already stopped)
+bool job_stop(int id);
+
+/// Writes data to the job's stdin. This is a non-blocking operation, it
+/// returns when the write request was sent.
+///
+/// @param id The job id
+/// @param data Buffer containing the data to be written
+/// @param len Size of the data
+/// @return true if the write request was successfully sent, false if the job
+///              id is invalid(probably because it has already stopped)
+bool job_write(int id, char *data, uint32_t len);
+
+/// Runs the read callback associated with the job exit event
+///
+/// @param event Object containing data necessary to invoke the callback
+void job_exit_event(Event event);
+
+/// Get the job id
+///
+/// @param job A pointer to the job
+/// @return The job id
+int job_id(Job *job);
+
+/// Get data associated with a job
+///
+/// @param job A pointer to the job
+/// @return The job data
+void *job_data(Job *job);
+
+#endif  // NEOVIM_OS_JOB_H
+