mirror of
https://github.com/mpv-player/mpv
synced 2024-12-27 17:42:17 +00:00
manpage: clarify some details about async. commands and "subprocess"
There's potential confusion about how long a process started with the "subprocess" command is allowed to live. Add some more explanations regarding "subprocess" specifics (such as the playback_only field), and things that apply to asynchronous commands in general. Partially for #7025.
This commit is contained in:
parent
fd7aff7a9d
commit
e49cec5832
@ -378,6 +378,9 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_).
|
||||
Similar to ``run``, but gives more control about process execution to the
|
||||
caller, and does does not detach the process.
|
||||
|
||||
You can avoid blocking until the process terminates by running this command
|
||||
asynchronously. (For example ``mp.command_native_async()`` in Lua scripting.)
|
||||
|
||||
This has the following named arguments. The order of them is not guaranteed,
|
||||
so you should always call them with named arguments, see `Named arguments`_.
|
||||
|
||||
@ -436,8 +439,10 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_).
|
||||
killed by mpv as a result of ``playback_only`` being set to ``yes``.
|
||||
|
||||
``killed_by_us`` (``MPV_FORMAT_FLAG``)
|
||||
Set to ``yes`` if the process has been killed by mpv as a result
|
||||
of ``playback_only`` being set to ``yes``.
|
||||
Set to ``yes`` if the process has been killed by mpv, for example as a
|
||||
result of ``playback_only`` being set to ``yes``, aborting the command
|
||||
(e.g. by ``mp.abort_async_command()``), or if the player is about to
|
||||
exit.
|
||||
|
||||
Note that the command itself will always return success as long as the
|
||||
parameters are correct. Whether the process could be spawned or whether
|
||||
@ -446,8 +451,15 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_).
|
||||
|
||||
This command can be asynchronously aborted via API.
|
||||
|
||||
In all cases, the subprocess will be terminated on player exit. Only the
|
||||
``run`` command can start processes in a truly detached way.
|
||||
In all cases, the subprocess will be terminated on player exit. Also see
|
||||
`Asynchronous command details`_. Only the ``run`` command can start
|
||||
processes in a truly detached way.
|
||||
|
||||
.. admonition:: Warning
|
||||
|
||||
Don't forget to set the ``playback_only`` field if you want the command
|
||||
run while the player is in idle mode, or if you don't want that end of
|
||||
playback kills the command.
|
||||
|
||||
``quit [<code>]``
|
||||
Exit the player. If an argument is given, it's used as process exit code.
|
||||
@ -1186,6 +1198,24 @@ sync vs. async: sub-add, audio-add, sub-reload, audio-reload,
|
||||
rescan-external-files, screenshot, screenshot-to-file, dump-cache,
|
||||
ab-loop-dump-cache.
|
||||
|
||||
Asynchronous command details
|
||||
----------------------------
|
||||
|
||||
On the API level, every asynchronous command is bound to the context which
|
||||
started it. For example, an asynchronous command started by ``mpv_command_async``
|
||||
is bound to the ``mpv_handle`` passed to the function. Only this ``mpv_handle``
|
||||
receives the completion notification (``MPV_EVENT_COMMAND_REPLY``), and only
|
||||
this handle can abort a still running command directly. If the ``mpv_handle`` is
|
||||
destroyed, any still running async. commands started by it are terminated.
|
||||
|
||||
The scripting APIs and JSON IPC give each script/connection its own implicit
|
||||
``mpv_handle``.
|
||||
|
||||
If the player is closed, the core may abort all pending async. commands on its
|
||||
own (like a forced ``mpv_abort_async_command()`` call for each pending command
|
||||
on behalf of the API user). This happens at the same time ``MPV_EVENT_SHUTDOWN``
|
||||
is sent, and there is no way to prevent this.
|
||||
|
||||
Input Sections
|
||||
--------------
|
||||
|
||||
|
@ -683,6 +683,8 @@ strictly part of the guaranteed API.
|
||||
directly, instead of calling this legacy wrapper. It is for compatibility
|
||||
only.
|
||||
|
||||
See the ``subprocess`` documentation for semantics and further parameters.
|
||||
|
||||
``utils.subprocess_detached(t)``
|
||||
Runs an external process and detaches it from mpv's control.
|
||||
|
||||
|
@ -111,6 +111,8 @@ extern "C" {
|
||||
* and asynchronous calls. If you want a guaranteed order, you need to wait
|
||||
* until asynchronous calls report completion before doing the next call.
|
||||
*
|
||||
* See also the section "Asynchronous command details" in the manpage.
|
||||
*
|
||||
* Multithreading
|
||||
* --------------
|
||||
*
|
||||
|
Loading…
Reference in New Issue
Block a user