mainloop-api: Improve pa_mainloop_api_once() documentation

[pulseaudio] / src / pulse / mainloop-api.h

diff --git a/src/pulse/mainloop-api.h b/src/pulse/mainloop-api.h
index e75496097d2ff403324ef5ce1e41e2e90eec3106..d03e0e6c8ab4f5f058a8ba05ac2fae9726e613fc 100644 (file)
--- a/src/pulse/mainloop-api.h
+++ b/src/pulse/mainloop-api.h
@@ -61,21 +61,21 @@ typedef enum pa_io_event_flags {
 typedef struct pa_io_event pa_io_event;
 /** An IO event callback prototype \since 0.9.3 */
 typedef void (*pa_io_event_cb_t)(pa_mainloop_api*ea, pa_io_event* e, int fd, pa_io_event_flags_t events, void *userdata);
-/** A IO event destroy callback prototype \ since 0.9.3 */
+/** A IO event destroy callback prototype \since 0.9.3 */
 typedef void (*pa_io_event_destroy_cb_t)(pa_mainloop_api*a, pa_io_event *e, void *userdata);
 
 /** An opaque timer event source object */
 typedef struct pa_time_event pa_time_event;
 /** A time event callback prototype \since 0.9.3 */
 typedef void (*pa_time_event_cb_t)(pa_mainloop_api*a, pa_time_event* e, const struct timeval *tv, void *userdata);
-/** A time event destroy callback prototype \ since 0.9.3 */
+/** A time event destroy callback prototype \since 0.9.3 */
 typedef void (*pa_time_event_destroy_cb_t)(pa_mainloop_api*a, pa_time_event *e, void *userdata);
 
 /** An opaque deferred event source object. Events of this type are triggered once in every main loop iteration */
 typedef struct pa_defer_event pa_defer_event;
 /** A defer event callback prototype \since 0.9.3 */
 typedef void (*pa_defer_event_cb_t)(pa_mainloop_api*a, pa_defer_event* e, void *userdata);
-/** A defer event destroy callback prototype \ since 0.9.3 */
+/** A defer event destroy callback prototype \since 0.9.3 */
 typedef void (*pa_defer_event_destroy_cb_t)(pa_mainloop_api*a, pa_defer_event *e, void *userdata);
 
 /** An abstract mainloop API vtable */
@@ -114,9 +114,11 @@ struct pa_mainloop_api {
     void (*quit)(pa_mainloop_api*a, int retval);
 };
 
-/** Run the specified callback function once from the main loop using an anonymous defer event. Note that this performs
- * multiple mainloop operations non-atomically. If, for example, you are using a \pa_threaded_mainloop, you will need to
- * take the mainloop lock before this call. */
+/** Run the specified callback function once from the main loop using an
+ * anonymous defer event. If the mainloop runs in a different thread, you need
+ * to follow the mainloop implementation's rules regarding how to safely create
+ * defer events. In particular, if you're using \ref pa_threaded_mainloop, you
+ * must lock the mainloop before calling this function. */
 void pa_mainloop_api_once(pa_mainloop_api*m, void (*callback)(pa_mainloop_api*m, void *userdata), void *userdata);
 
 PA_C_DECL_END