From 351a237b2df497e78ac2d4666040e02118e924e8 Mon Sep 17 00:00:00 2001 From: Takashi Sakamoto Date: Mon, 27 Jun 2022 09:24:29 +0900 Subject: [PATCH] mixer: add documentation about postcondition of removal event processing PulseAudio and PipeWire seems to appear including careless code to process events of mixer element in implementation of mixer class. * https://lore.kernel.org/alsa-devel/YrbxZ2b+3rIdi7Ut@workstation/ They register own implementation of mixer class. At addition event, they attach own mixer element into hcontrol element. However at removal event, they never detach the mixer element from hcontrol element. They hit assertion in mixer API internal due to unsatisfied postcondition. This commit adds documentation about postcondition of removal event processing so that developer for implementation of mixer class easily realize the way to satisfy the postcondition. Fixes: https://github.com/alsa-project/alsa-lib/pull/244 Signed-off-by: Takashi Sakamoto Signed-off-by: Jaroslav Kysela --- src/mixer/mixer.c | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/src/mixer/mixer.c b/src/mixer/mixer.c index b1af9945..7019d6f4 100644 --- a/src/mixer/mixer.c +++ b/src/mixer/mixer.c @@ -87,6 +87,11 @@ int snd_mixer_open(snd_mixer_t **mixerp, int mode ATTRIBUTE_UNUSED) * \return 0 on success otherwise a negative error code * * For use by mixer element class specific code. + * + * The implementation of mixer class typically calls it at #SND_CTL_EVENT_MASK_ADD event. Once + * attaching, the implementation should make sure to detach it by call of #snd_mixer_elem_detach() + * at #SND_CTL_EVENT_MASK_REMOVE event. Unless detaching, mixer API internal hits assertion due + * to unsatisfied postcondition after the event. */ int snd_mixer_elem_attach(snd_mixer_elem_t *melem, snd_hctl_elem_t *helem) @@ -106,6 +111,10 @@ int snd_mixer_elem_attach(snd_mixer_elem_t *melem, * \return 0 on success otherwise a negative error code * * For use by mixer element class specific code. + * + * The implementation of mixer class typically calls it at #SND_CTL_EVENT_MASK_REMOVE event for + * attached mixer element at #SND_CTL_EVENT_MASK_ADD. Unless detaching, mixer API internal hits + * assertion due to unsatisfied postcondition after the event. */ int snd_mixer_elem_detach(snd_mixer_elem_t *melem, snd_hctl_elem_t *helem) @@ -146,6 +155,9 @@ static int hctl_elem_event_handler(snd_hctl_elem_t *helem, if (err < 0) res = err; } + // NOTE: Unsatisfied postcondition. Typically, some of registerd implementation of + // mixer class forget to detach mixer element from hcontrol element which has been + // attached at ADD event. assert(bag_empty(bag)); bag_free(bag); return res; -- 2.47.1