client API: turn mpv_suspend() and mpv_resume() into stubs

As threatened by the API changes document.

This commit also removes or stubs equivalent calls in IPC and Lua
scripting.

The stubs are left to maintain ABI compatibility. The semantics of the
API functions have been close enough to doing nothing that this probably
won't even break existing API users. Probably.

DOCS/client-api-changes.rst

@@ -32,6 +32,8 @@ API changes
 
 ::
 
+ --- mpv 0.23.0 ---
+ 1.24   - the deprecated mpv_suspend() and mpv_resume() APIs now do nothing.
  --- mpv 0.22.0 ---
  1.23   - deprecate setting "no-" options via mpv_set_option*(). For example,
           instead of "no-video=" you should set "video=no".

DOCS/man/ipc.rst

@@ -241,20 +241,6 @@ extra commands can also be used as part of the protocol:
     By default, most events are enabled, and there is not much use for this
     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.
-
 ``get_version``
     Returns the client API version the C API of the remote mpv instance
     provides.

DOCS/man/lua.rst

@@ -43,9 +43,8 @@ timers added with ``mp.add_timeout`` or similar.
 
 When the player quits, all scripts will be asked to terminate. This happens via
 a ``shutdown`` event, which by default will make the event loop return. If your
-script got into an endless loop, mpv will probably behave fine during playback
+script got into an endless loop, mpv will probably behave fine during playback,
-(unless the player is suspended, see ``mp.suspend``), but it won't terminate
+but it won't terminate when quitting, because it's waiting on your script.
-when quitting, because it's waiting on your script.
 
 Internally, the C code will call the Lua function ``mp_event_loop`` after
 loading a Lua script. This function is normally defined by the default prelude
@@ -412,27 +411,16 @@ These also live in the ``mp`` module, but are documented separately as they
 are useful only in special situations.
 
 ``mp.suspend()``
-    This function has been deprecated in mpv 0.21.0 (no replacement).
+    This function has been deprecated in mpv 0.21.0 and does nothing starting
-
+    with mpv 0.23.0 (no replacement).
-    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.
-
-    Before mpv 0.17.0, this was automatically called by the event handler.
 
 ``mp.resume()``
-    This function has been deprecated in mpv 0.21.0 (no replacement).
+    This function has been deprecated in mpv 0.21.0 and does nothing starting
-
+    with mpv 0.23.0 (no replacement).
-    Undo one ``mp.suspend()`` call. ``mp.suspend()`` increments an internal
-    counter, and ``mp.resume()`` decrements it. When 0 is reached, the player
-    is actually resumed.
 
 ``mp.resume_all()``
-    This function has been deprecated in mpv 0.21.0 (no replacement).
+    This function has been deprecated in mpv 0.21.0 and does nothing starting
-
+    with mpv 0.23.0 (no replacement).
-    This resets the internal suspend counter and resumes the player. (It's
-    like calling ``mp.resume()`` until the player is actually resumed.)
 
 ``mp.get_wakeup_pipe()``
     Calls ``mpv_get_wakeup_pipe()`` and returns the read end of the wakeup

input/ipc.c

@@ -384,12 +384,6 @@ static char *json_execute_command(struct mpv_handle *client, void *ta_parent,
 
         rc = mpv_request_log_messages(client,
                                       cmd_node->u.list->values[1].u.string);
-    } else if (!strcmp("suspend", cmd)) {
-        mpv_suspend(client);
-        rc = MPV_ERROR_SUCCESS;
-    } else if (!strcmp("resume", cmd)) {
-        mpv_resume(client);
-        rc = MPV_ERROR_SUCCESS;
     } else if (!strcmp("enable_event", cmd) ||
                !strcmp("disable_event", cmd))
     {

libmpv/client.h

@@ -211,7 +211,7 @@ extern "C" {
  * relational operators (<, >, <=, >=).
  */
 #define MPV_MAKE_VERSION(major, minor) (((major) << 16) | (minor) | 0UL)
-#define MPV_CLIENT_API_VERSION MPV_MAKE_VERSION(1, 23)
+#define MPV_CLIENT_API_VERSION MPV_MAKE_VERSION(1, 24)
 
 /**
  * Return the MPV_CLIENT_API_VERSION the mpv source has been compiled with.
@@ -506,6 +506,9 @@ mpv_handle *mpv_create_client(mpv_handle *ctx, const char *name);
 int mpv_load_config_file(mpv_handle *ctx, const char *filename);
 
 /**
+ * This does nothing since mpv 0.23.0 (API version 1.24). Below is the
+ * description of the old behavior.
+ *
  * Stop the playback thread. This means the core will stop doing anything, and
  * only run and answer to client API requests. This is sometimes useful; for
  * example, no new frame will be queued to the video output, so doing requests

player/client.c

@@ -329,59 +329,11 @@ void mpv_set_wakeup_callback(mpv_handle *ctx, void (*cb)(void *d), void *d)
 
 void mpv_suspend(mpv_handle *ctx)
 {
-    bool do_suspend = false;
+    MP_ERR(ctx, "mpv_suspend() is deprecated and does nothing.\n");
-
-    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");
-    } else {
-        do_suspend = ctx->suspend_count == 0;
-        ctx->suspend_count++;
-    }
-    pthread_mutex_unlock(&ctx->lock);
-
-    if (do_suspend) {
-        mp_dispatch_lock(ctx->mpctx->dispatch);
-        ctx->mpctx->suspend_count++;
-        mp_dispatch_unlock(ctx->mpctx->dispatch);
-    }
 }
 
 void mpv_resume(mpv_handle *ctx)
 {
-    bool do_resume = false;
-
-    pthread_mutex_lock(&ctx->lock);
-    if (ctx->suspend_count == 0) {
-        MP_ERR(ctx, "suspend counter underflow");
-    } else {
-        do_resume = ctx->suspend_count == 1;
-        ctx->suspend_count--;
-    }
-    pthread_mutex_unlock(&ctx->lock);
-
-    if (do_resume) {
-        mp_dispatch_lock(ctx->mpctx->dispatch);
-        ctx->mpctx->suspend_count--;
-        mp_dispatch_unlock(ctx->mpctx->dispatch);
-        mp_dispatch_interrupt(ctx->mpctx->dispatch);
-    }
-}
-
-void mp_resume_all(mpv_handle *ctx)
-{
-    pthread_mutex_lock(&ctx->lock);
-    bool do_resume = ctx->suspend_count > 0;
-    ctx->suspend_count = 0;
-    pthread_mutex_unlock(&ctx->lock);
-
-    if (do_resume) {
-        mp_dispatch_lock(ctx->mpctx->dispatch);
-        ctx->mpctx->suspend_count--;
-        mp_dispatch_unlock(ctx->mpctx->dispatch);
-    }
 }
 
 static void lock_core(mpv_handle *ctx)
@@ -396,8 +348,6 @@ static void unlock_core(mpv_handle *ctx)
 
 void mpv_wait_async_requests(mpv_handle *ctx)
 {
-    mp_resume_all(ctx);
-
     pthread_mutex_lock(&ctx->lock);
     while (ctx->reserved_events || ctx->properties_updating)
         wait_wakeup(ctx, INT64_MAX);

player/client.h

@@ -35,8 +35,6 @@ struct mp_log *mp_client_get_log(struct mpv_handle *ctx);
 struct MPContext *mp_client_get_core(struct mpv_handle *ctx);
 struct MPContext *mp_client_api_get_core(struct mp_client_api *api);
 
-void mp_resume_all(struct mpv_handle *ctx);
-
 // m_option.c
 void *node_get_alloc(struct mpv_node *node);
 

player/core.h

@@ -226,7 +226,6 @@ enum playback_status {
 typedef struct MPContext {
     bool initialized;
     bool autodetach;
-    int suspend_count;
     struct mpv_global *global;
     struct MPOpts *opts;
     struct mp_log *log;

player/lua.c

@@ -393,7 +393,6 @@ static int load_lua(struct mpv_handle *client, const char *fname)
     r = 0;
 
 error_out:
-    mp_resume_all(client);
     if (ctx->state)
         lua_close(ctx->state);
     talloc_free(ctx);
@@ -451,22 +450,17 @@ 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 "
+    MP_ERR(ctx, "mp.suspend() is deprecated and does nothing.\n");
-                 "deprecated.\n");
-    mpv_suspend(ctx->client);
     return 0;
 }
 
 static int script_resume(lua_State *L)
 {
-    struct script_ctx *ctx = get_ctx(L);
-    mpv_resume(ctx->client);
     return 0;
 }
 
 static int script_resume_all(lua_State *L)
 {
-    mp_resume_all(get_ctx(L)->client);
     return 0;
 }
 
@@ -1134,8 +1128,6 @@ static int script_subprocess(lua_State *L)
     luaL_checktype(L, 1, LUA_TTABLE);
     void *tmp = mp_lua_PITA(L);
 
-    mp_resume_all(ctx->client);
-
     lua_getfield(L, 1, "args"); // args
     int num_args = mp_lua_len(L, -1);
     char *args[256];
@@ -1193,8 +1185,6 @@ static int script_subprocess_detached(lua_State *L)
     luaL_checktype(L, 1, LUA_TTABLE);
     void *tmp = mp_lua_PITA(L);
 
-    mp_resume_all(ctx->client);
-
     lua_getfield(L, 1, "args"); // args
     int num_args = mp_lua_len(L, -1);
     char *args[256];

player/lua/defaults.lua

@@ -452,10 +452,15 @@ end
 
 mp.use_suspend = false
 
+local suspend_warned = false
+
 function mp.dispatch_events(allow_wait)
     local more_events = true
     if mp.use_suspend then
-        mp.suspend()
+        if not suspend_warned then
+            mp.msg.error("mp.use_suspend is now ignored.")
+            suspend_warned = true
+        end
     end
     while mp.keep_running do
         local wait = 0
@@ -475,11 +480,6 @@ function mp.dispatch_events(allow_wait)
             end
         end
         local e = mp.wait_event(wait)
-        -- Empty the event queue while suspended; otherwise, each
-        -- event will keep us waiting until the core suspends again.
-        if mp.use_suspend then
-            mp.suspend()
-        end
         more_events = false
         if e.event ~= "none" then
             call_event_handlers(e)

player/playloop.c

@@ -62,9 +62,6 @@ void mp_wait_events(struct MPContext *mpctx)
 
     mp_dispatch_queue_process(mpctx->dispatch, mpctx->sleeptime);
 
-    while (mpctx->suspend_count)
-        mp_dispatch_queue_process(mpctx->dispatch, 100);
-
     mpctx->in_dispatch = false;
     mpctx->sleeptime = INFINITY;