New Process Primitives in Epsilon 10

Lugaru's Epsilon
Programmer's
Editor 14.04

Previous	Up	Next
New Buffer Primitives in Epsilon 10	Changes from Older Versions	New OS-Specific Primitives in Epsilon 10

Epsilon User's Manual and Reference > Changes from Older Versions > New EEL Primitives and Subroutines in Epsilon 10 >

New Process Primitives in Epsilon 10

leave(?int exitcode)

The leave( ) primitive now takes an optional parameter to specify an exit code. If omitted, Epsilon exits with exit code 0.

int pipe_text(char *input, char *output, char *cmdline, char *curdir, int flags, int handler) my_handler(int activity, int buf, int from, int to) // Sample. int buf_pipe_text(int inputb, int outputb, char *cmdline, char *curdir, int flags)
The pipe_text( ) subroutine runs the program specified by cmdline, passing it the contents of a buffer as its standard input, and inserting its standard output into a second buffer (or the same buffer).

Either the input or output buffer names may be NULL. Epsilon provides a current directory of curdir, or uses Epsilon's current directory if curdir is NULL or "". The subroutine returns 0 and sets errno if the function could not be started, or returns 1 if the function started successfully.

The PIPE_SYNCH flag means don't return from the subroutine until the process has finished. Otherwise, Epsilon starts the subprocess and then returns from pipe_text( ), letting the subprocess run asynchronously.

The PIPE_CLEAR_BUF flag means empty the output buffer before inserting the process's text (but do nothing if the process can't be started); it's convenient when the input and output buffers are the same, to filter a buffer in place.

The PIPE_NOREFRESH flag tells Epsilon not to refresh the screen each time more data is received from the process, and is most useful with PIPE_SYNCH if you don't want the user to see the data until after it's been processed.

If handler is nonzero, it's the index of a function (or a function pointer) to call each time text is received from the process, and when the process terminates. You must specify an output buffer for a handler to be called. The handler function will be called with the buffer number into which more process output has just been inserted, and from and to set to indicate the new text. The parameter activity will be NET_RECV when characters have been received, or NET_DONE when the subprocess has exited. In the latter case from will hold the process exit code.

The pipe_text( ) subroutine described above is implemented using the buf_pipe_text( ) primitive. There are a few differences between these:

The buf_pipe_text( ) primitive uses buffer numbers, not buffer names. It won't create a buffer for you the way the subroutine will; the buffer must already exist. (Pass 0 for a buffer number if you don't need input or output.)

Instead of passing a function pointer for handler, you must instead set the buffer-specific when_activity variable in the output buffer prior to calling buf_pipe_text( ).

Pass a curdir of "", not NULL, to buf_pipe_text( ) to use Epsilon's current directory.

The pipe_text( ) and buf_pipe_text( ) functions are only available in Epsilon for Unix and Epsilon for 32-bit Windows.

int halt_process(?int hard_kill, int buf) int process_input(?int buf) int process_kill(?int buf) int concur_shell(char *program, char *cline, ?char *curdir, char *buf) short another_process(); int is_process_buffer(int buf)
To support multiple concurrent processes, the primitives halt_process( ), process_input( ), and process_kill( ) now take one additional optional parameter, a buffer number. If omitted or zero, the buffer named "process" is assumed.

The concur_shell( ) primitive now accepts a current directory parameter and a buffer name. If the current directory is null or both are omitted, Epsilon's current directory will be used for the new process. (At this writing, some versions of Epsilon always use Epsilon's current directory for the new process.) In versions of Epsilon that support multiple concurrent processes, the specified buffer will be used instead of "process".

The another_process( ) primitive now returns the number of active concurrent process buffers, and the is_process_buffer( ) tells if a particular buffer has a concurrent process. The process_exit_status variable provides a process's exit status code.

buffer int (*when_activity)(); concur_handler(int activity, int buf, int from, int to)
Whenever Epsilon receives process output or sends it input, it calls an EEL function. This interface has changed to support multiple processes; it's now similar to the one used for Internet activity.

The buffer-specific when_activity variable contains a function pointer to the function to call. If the variable is zero in a buffer, Epsilon won't call any EEL function as it proceeds. For a typical process buffer, the when_activity variable points to the concur_activity( ) subroutine.

Just after a concurrent process inserts output in a process buffer, it calls this subroutine, passing NET_RECV as the activity. The from and to parameters mark the range of buffer text that was just received from the process. The concur_activity( ) subroutine responds to this message by coloring the inserted characters with the color_class process_output color, and similar tasks.

Epsilon calls this subroutine and passes NET_SEND when it detects that the concurrent process is now ready for input, and again as it sends the input to the process. When the process becomes ready for input, the subroutine will be called with a from parameter of zero. When the process is sent a line of text, the subroutine will be called with a from of PROCESS_INPUT_LINE, and when the process is sent a single character it will be called with a from of PROCESS_INPUT_CHAR. In each case the to parameter will indicate the beginning of the input text (the value of type_point before the input begins).

Epsilon calls this subroutine and passes NET_DONE when the process exits. Its from parameter will hold the exit code, or 0 if Epsilon didn't record this. Epsilon sets the buffer-specific process_exit_status variable to the value PROC_STATUS_RUNNING when a process starts, and sets it to the process exit status (or 0) when the process exits.

Epsilon for Unix often cannot detect when a process is awaiting input. Therefore process_input( ) always returns zero, and a NET_SEND activity will typically not be signaled with a from parameter of zero.

Previous Up Next
New Buffer Primitives in Epsilon 10 Changes from Older Versions New OS-Specific Primitives in Epsilon 10