[pulseaudio-discuss] [PATCH 1/2] mainloop: Document need for mainloop lock around pa_mainloop_api_once

[Arun Raghavan]

This needs us to expose a bit of implementation detail, but this seems
to be the cleanest way without an API change.

The specific problem is that pa_mainloop_api_once() needs to first
create a defer event and then set its destroy callback. If the defer
event is completed before the callback is set, an assert will be
trigerred.
---
 src/pulse/mainloop-api.h | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/pulse/mainloop-api.h b/src/pulse/mainloop-api.h
index 018ae19..e754960 100644
--- a/src/pulse/mainloop-api.h
+++ b/src/pulse/mainloop-api.h
@@ -114,7 +114,9 @@ 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. */
+/** 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. */
 void pa_mainloop_api_once(pa_mainloop_api*m, void (*callback)(pa_mainloop_api*m, void *userdata), void *userdata);
 
 PA_C_DECL_END
-- 
1.8.2.1