client API: declare mpv_suspend/mpv_resume deprecated

They're useless, and I have no idea what they're actually supposed to do
(wrt. pending input processing changes).

Also remove their implicit uses from the IPC handlers.

DOCS/client-api-changes.rst

@@ -39,6 +39,8 @@ API changes
           mpv_initialize().
         - do not override the SIGPIPE signal handler anymore. This was done as
           workaround for the FFmpeg TLS code, which has been fixed long ago.
+        - deprecate mpv_suspend() and mpv_resume(). They will be stubbed out
+          in mpv 0.22.0.
  --- mpv 0.19.0 ---
  1.22   - add stream_cb API for custom protocols
  --- mpv 0.18.1 ---

DOCS/interface-changes.rst

@@ -63,6 +63,11 @@ Interface changes
       treating it as a hardware overlay (without applying GL filtering). Also
       to be changed in 0.22.0: the --fs flag will be reset to "no" by default
       (like on the other platforms).
+    - deprecate "resume" and "suspend" IPC commands. They will be completely
+      removed in 0.22.0.
+    - deprecate mp.suspend(), mp.resume(), mp.resume_all() Lua scripting
+      commands, as well as setting mp.use_suspend. They will be completely
+      removed in 0.22.0.
     - add almost all options to the property list, meaning you can change
       options without adding "options/" to the property name (a new section
       has been added to the manpage describing some conflicting behavior

DOCS/man/ipc.rst

@@ -242,12 +242,16 @@ extra commands can also be used as part of the protocol:
     command.
 
 ``suspend``
+    Deprecated, will be removed completely in 0.21.0.
+
     Suspend the mpv main loop. There is a long-winded explanation of this in
     the C API function ``mpv_suspend()``. In short, this prevents the player
     from displaying the next video frame, so that you don't get blocked when
     trying to access the player.
 
 ``resume``
+    Deprecated, will be removed completely in 0.21.0.
+
     Undo one ``suspend`` call. ``suspend`` increments an internal counter, and
     ``resume`` decrements it. When 0 is reached, the player is actually resumed.
 

input/ipc-unix.c

@@ -124,15 +124,11 @@ static void *client_thread(void *p)
     };
 
     fcntl(arg->client_fd, F_SETFL, fcntl(arg->client_fd, F_GETFL, 0) | O_NONBLOCK);
-    mpv_suspend(arg->client);
 
     while (1) {
         rc = poll(fds, 2, 0);
-        if (rc == 0) {
-            mpv_resume(arg->client);
+        if (rc == 0)
             rc = poll(fds, 2, -1);
-            mpv_suspend(arg->client);
-        }
         if (rc < 0) {
             MP_ERR(arg, "Poll error\n");
             continue;

input/ipc-win.c

@@ -222,7 +222,6 @@ static void *client_thread(void *p)
     MP_VERBOSE(arg, "Client connected\n");
 
     mpv_set_wakeup_callback(arg->client, wakeup_cb, wakeup_event);
-    mpv_suspend(arg->client);
 
     // Do the first read operation on the pipe
     if ((ioerr = async_read(arg->client_h, buf, 4096, &ol))) {
@@ -233,11 +232,8 @@ static void *client_thread(void *p)
     while (1) {
         HANDLE handles[] = { wakeup_event, ol.hEvent };
         int n = WaitForMultipleObjects(2, handles, FALSE, 0);
-        if (n == WAIT_TIMEOUT) {
-            mpv_resume(arg->client);
+        if (n == WAIT_TIMEOUT)
             n = WaitForMultipleObjects(2, handles, FALSE, INFINITE);
-            mpv_suspend(arg->client);
-        }
 
         switch (n) {
         case WAIT_OBJECT_0: // wakeup_event

libmpv/client.h

@@ -515,6 +515,11 @@ int mpv_load_config_file(mpv_handle *ctx, const char *filename);
  * mpv_suspend() is not allowed.
  *
  * Calling this on an uninitialized player (see mpv_create()) will deadlock.
+ *
+ * @deprecated This function, as well as mpv_resume(), are deprecated, and
+ *             will stop doing anything soon. Their semantics were never
+ *             well-defined, and their usefulness is extremely limited. The
+ *             calls will remain stubs in order to keep ABI compatibility.
  */
 void mpv_suspend(mpv_handle *ctx);
 

player/client.c

@@ -321,6 +321,8 @@ void mpv_suspend(mpv_handle *ctx)
 {
     bool do_suspend = false;
 
+    MP_WARN(ctx, "warning: mpv_suspend() is deprecated.\n");
+
     pthread_mutex_lock(&ctx->lock);
     if (ctx->suspend_count == INT_MAX) {
         MP_ERR(ctx, "suspend counter overflow");

player/lua.c

@@ -450,6 +450,8 @@ static int script_find_config_file(lua_State *L)
 static int script_suspend(lua_State *L)
 {
     struct script_ctx *ctx = get_ctx(L);
+    MP_WARN(ctx, "mp.suspend() (possibly triggered by mp.use_suspend) is "
+                 "deprecated.\n");
     mpv_suspend(ctx->client);
     return 0;
 }