From ede6da692ae95d9b2ac68173b70ab43566d1401f Mon Sep 17 00:00:00 2001 From: Zeno Endemann Date: Fri, 24 Nov 2023 14:33:47 +0100 Subject: [PATCH] pcm: clarify documentation of poll descriptor usage This is based on my understanding of the intended behavior, the test/pcm.c example code, as well as the github pull request discussion (#370). There needs to be more clarifiaction regarding the exact semantics of the value of the revents output parameter of snd_pcm_poll_descriptors_revents, since there are events that do not necessarily correspond to POLLIN or POLLOUT (such as period events), but I believe this is a lot less obvious and needs confirmation first. --- src/pcm/pcm.c | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/src/pcm/pcm.c b/src/pcm/pcm.c index ad9e8956..94b0bc52 100644 --- a/src/pcm/pcm.c +++ b/src/pcm/pcm.c @@ -1808,6 +1808,11 @@ static int __snd_pcm_poll_descriptors(snd_pcm_t *pcm, struct pollfd *pfds, * corresponding FD_SET arrays and demangle events using * \link ::snd_pcm_poll_descriptors_revents() \endlink . * + * It is guaranteed that for the given PCM handle, the output poll + * descriptor structs (and their count) will never change, thus it is + * valid to call the function once and reuse its output for the + * lifetime of the PCM device. + * * The function is thread-safe when built with the proper option. */ int snd_pcm_poll_descriptors(snd_pcm_t *pcm, struct pollfd *pfds, unsigned int space) @@ -1843,6 +1848,13 @@ static int __snd_pcm_poll_revents(snd_pcm_t *pcm, struct pollfd *pfds, * Note: Even if multiple poll descriptors are used (i.e. pfds > 1), * this function returns only a single event. * + * The passed in count of poll descriptors must be equal to + * \link ::snd_pcm_poll_descriptors_count() \endlink and the passed in array + * must match the array returned by \link ::snd_pcm_poll_descriptors() \endlink + * (in its full length and original order) with the revent fields updated + * according to the poll() result. This function will not modify the file + * descriptor or event field of any element of the given poll descriptor array. + * * The function is thread-safe when built with the proper option. */ int snd_pcm_poll_descriptors_revents(snd_pcm_t *pcm, struct pollfd *pfds, unsigned int nfds, unsigned short *revents)