Process API

Functions
struct vlc_process *	vlc_process_Spawn (const char *path, int argc, const char *const *argv)
	Spawn a new process with input and output redirection.
void	vlc_process_Kill (struct vlc_process *process)
	Kill a process and abort its I/O.
int	vlc_process_Terminate (struct vlc_process *process, bool kill_process)
	Stop a vlc_process and wait for its termination.
ssize_t	vlc_process_fd_Read (struct vlc_process *process, uint8_t *buf, size_t size, vlc_tick_t timeout_ms)
	Read data from the process's standard output with a timeout.
ssize_t	vlc_process_fd_Write (struct vlc_process *process, const uint8_t *buf, size_t size, vlc_tick_t timeout_ms)
	Write data to the process's standard input with a timeout.

Detailed Description

Function Documentation

vlc_process_fd_Read()

ssize_t vlc_process_fd_Read	(	struct vlc_process *	process,
		uint8_t *	buf,
		size_t	size,
		vlc_tick_t	timeout_ms )

Read data from the process's standard output with a timeout.

Attempts to read up to size bytes from the process's standard output into the provided buffer, waiting up to timeout_ms milliseconds for data to become available.

On POSIX systems, this uses poll to wait for readability. On Windows, a platform-specific implementation is used due to limitations with poll on non-socket handles.

Warning

At most one thread may call this function on a given process at a time. Reading from one thread while another one writes is supported, but two concurrent readers are not.

Parameters

[in]	process	Pointer to the vlc_process instance.
[out]	buf	Buffer where the read data will be stored.
[in]	size	Maximum number of bytes to read.
[in]	timeout_ms	Timeout in milliseconds to wait for data.

Returns

The number of bytes read on success, -1 on error, and errno is set to indicate the error.

References vlc_process::fd, vlc_process::fd_in, vlc_process::hEventRead, vlc_process::killed, POLLIN, pollfd::revents, vlc_assert_unreachable, vlc_poll_i11e(), vlc_process_WindowsMapIoResult(), vlc_process_WindowsPoll(), VLC_SUCCESS, and VLC_UNUSED.

Referenced by read_cbs().

vlc_process_fd_Write()

ssize_t vlc_process_fd_Write	(	struct vlc_process *	process,
		const uint8_t *	buf,
		size_t	size,
		vlc_tick_t	timeout_ms )

Write data to the process's standard input with a timeout.

Attempts to write up to size bytes from the provided buffer to the process's standard input, waiting up to timeout_ms milliseconds for the pipe to become writable.

On POSIX systems, this uses poll to wait for writability. On Windows, a platform-specific implementation is used due to limitations with poll on non-socket handles.

Warning

At most one thread may call this function on a given process at a time. Writing from one thread while another one reads is supported, but two concurrent writers are not.

Parameters

[in]	process	Pointer to the vlc_process instance.
[in]	buf	Buffer containing the data to write.
[in]	size	Number of bytes to write.
[in]	timeout_ms	Timeout in milliseconds to wait for the pipe to be writable.

Returns

The number of bytes written on success, -1 on error, and errno is set to indicate the error.

References vlc_process::fd, vlc_process::fd_out, vlc_process::hEventWrite, vlc_process::killed, POLLOUT, pollfd::revents, vlc_assert_unreachable, vlc_poll_i11e(), vlc_process_WindowsMapIoResult(), vlc_process_WindowsPoll(), vlc_send_i11e(), VLC_SUCCESS, and VLC_UNUSED.

Referenced by write_cbs().

vlc_process_Kill()

void vlc_process_Kill

(

struct vlc_process *

process

)

Kill a process and abort its I/O.

Sends a termination signal to the process and shuts down the communication channel, so that any in-flight or subsequent I/O on process completes promptly instead of blocking: vlc_process_fd_Read() reports end-of-stream and vlc_process_fd_Write() fails with EPIPE.

This does not free process: vlc_process_Terminate() must still be called for that. It can be called multiple times.

Parameters

[in]

process

Pointer to the vlc_process instance. Must not be NULL.

References vlc_process::fd, vlc_process::fd_in, vlc_process::fd_out, vlc_process::hProcess, vlc_process::killed, vlc_process::pid, vlc_assert_unreachable, and VLC_UNUSED.

Referenced by preparser_pool_Delete(), and vlc_process_Terminate().

vlc_process_Spawn()

struct vlc_process * vlc_process_Spawn	(	const char *	path,
		int	argc,
		const char *const *	argv )

Spawn a new process with input and output redirection.

Creates and starts a new vlc_process for the specified executable path with the given arguments. Sets up pipes to allow reading from the process's standard output and writing to its standard input.

Parameters

[in]	path	Path to the executable to run. Must not be NULL.
[in]	argc	Number of arguments passed to the process (must be greater than or equal to 0).
[in]	argv	Array of argument strings. May be NULL if argc is 0; otherwise argv[0] must not be NULL.

Returns

A pointer to the newly created vlc_process structure on success, or NULL on failure.

References vlc_process::fd, vlc_process::fd_in, vlc_process::fd_out, vlc_process::hEventRead, vlc_process::hEventWrite, vlc_process::hProcess, vlc_process::killed, net_Close, vlc_process::pid, vlc_close(), vlc_dup(), VLC_EGENERIC, VLC_ENOMEM, vlc_pipe(), vlc_socketpair(), vlc_spawnp(), and VLC_UNUSED.

Referenced by preparser_pool_SpawnProcess().

vlc_process_Terminate()

int vlc_process_Terminate	(	struct vlc_process *	process,
		bool	kill_process )

Stop a vlc_process and wait for its termination.

Closes its file descriptors, and waits for it to exit. Optionally sends a termination signal to the process,

Warning

This must not be called concurrently with vlc_process_fd_Read() or vlc_process_fd_Write() on the same process. It closes the underlying pipe/socket and frees process, so the caller must ensure that any thread performing I/O has returned first to avoid a use-after-free. Use vlc_process_Kill() to unblock such a thread, then join it before calling this.

Parameters

[in]	process	Pointer to the vlc_process instance. Must not be NULL.
[in]	kill_process	Whether to forcibly terminate the process before waiting.

Returns

The exit status of the process, or -1 on error.

References vlc_process::fd, vlc_process::fd_in, vlc_process::fd_out, vlc_process::hEventRead, vlc_process::hEventWrite, vlc_process::hProcess, net_Close, vlc_process::pid, vlc_assert_unreachable, vlc_close(), vlc_process_Kill(), VLC_UNUSED, and vlc_waitpid().

Referenced by preparser_pool_Delete(), preparser_pool_JoinStoppedThreadsLocked(), preparser_pool_Run(), and preparser_pool_SpawnThreadLocked().