From 9e64b9382265fb688fecda15b28ad6c41b587cd6 Mon Sep 17 00:00:00 2001 From: wm4 Date: Wed, 24 Jan 2018 02:00:02 +0100 Subject: client API: be more explicit about what can be done in wakeup callbacks Don't leave any room for interpretation. --- libmpv/client.h | 18 +++++++++++++----- libmpv/opengl_cb.h | 3 ++- 2 files changed, 15 insertions(+), 6 deletions(-) diff --git a/libmpv/client.h b/libmpv/client.h index bc2fff0563..f3e4d4c8c8 100644 --- a/libmpv/client.h +++ b/libmpv/client.h @@ -1588,11 +1588,19 @@ void mpv_wakeup(mpv_handle *ctx); * * Keep in mind that the callback will be called from foreign threads. You * must not make any assumptions of the environment, and you must return as - * soon as possible. You are not allowed to call any client API functions - * inside of the callback. In particular, you should not do any processing in - * the callback, but wake up another thread that does all the work. It's also - * possible that the callback is called from a thread while a mpv API function - * is called (i.e. it can be reentrant). + * soon as possible (i.e. no long blocking waits). Exiting the callback through + * any other means than a normal return is forbidden (no throwing exceptions, + * no longjmp() calls). You must not change any local thread state (such as + * the C floating point environment). + * + * You are not allowed to call any client API functions inside of the callback. + * In particular, you should not do any processing in the callback, but wake up + * another thread that does all the work. The callback is meant strictly for + * notification only, and is called from arbitrary core parts of the player, + * that make no considerations for reentrant API use or allowing the callee to + * spend a lot of time doing other things. Keep in mind that it's also possible + * that the callback is called from a thread while a mpv API function is called + * (i.e. it can be reentrant). * * In general, the client API expects you to call mpv_wait_event() to receive * notifications, and the wakeup callback is merely a helper utility to make diff --git a/libmpv/opengl_cb.h b/libmpv/opengl_cb.h index 4172611dc5..4025d745fa 100644 --- a/libmpv/opengl_cb.h +++ b/libmpv/opengl_cb.h @@ -252,7 +252,8 @@ typedef void *(*mpv_opengl_cb_get_proc_address_fn)(void *fn_ctx, const char *nam * Set the callback that notifies you when a new video frame is available, or * if the video display configuration somehow changed and requires a redraw. * Similar to mpv_set_wakeup_callback(), you must not call any mpv API from - * the callback. + * the callback, and all the other listed restrictions apply (such as not + * exiting the callback by throwing exceptions). * * @param callback callback(callback_ctx) is called if the frame should be * redrawn -- cgit v1.2.3