From e1a3e2468bcbea44b89d543fac5ada7f531de907 Mon Sep 17 00:00:00 2001
From: derselbst <tom.mbrt@googlemail.com>
Date: Thu, 17 May 2018 15:36:38 +0200
Subject: [PATCH] require explicit unregistering of sequencer clients

---
 doc/fluidsynth-v11-devdoc.txt |  1 +
 src/midi/fluid_seq.c          |  3 +++
 src/midi/fluid_seqbind.c      | 21 +++++++++++++++++++++
 3 files changed, 25 insertions(+)

diff --git a/doc/fluidsynth-v11-devdoc.txt b/doc/fluidsynth-v11-devdoc.txt
index 45b352bd..d77c1bec 100644
--- a/doc/fluidsynth-v11-devdoc.txt
+++ b/doc/fluidsynth-v11-devdoc.txt
@@ -103,6 +103,7 @@ Changes in FluidSynth 2.0.0 concerning developers:
 - all public \c fluid_settings_* functions that return an integer which is not meant to be interpreted as bool consistently return either FLUID_OK or FLUID_FAILED
 - all public delete_* functions return void and are safe when called with NULL
 - all public functions consistently receive signed integers for soundfont ids, bank and program numbers
+- explicit client unregistering is required for fluid_sequencer_register_client() and fluid_sequencer_register_fluidsynth()
 - the shell command handler was decoupled internally, as a consequence the param list of new_fluid_server() and new_fluid_cmd_handler() was adapted
 - reverb: roomsize is now limited to an upper threshold of 1.0 to avoid exponential volume increase
 - use unique device names for the "audio.portaudio.device" setting
diff --git a/src/midi/fluid_seq.c b/src/midi/fluid_seq.c
index f273ec72..5dfb22be 100644
--- a/src/midi/fluid_seq.c
+++ b/src/midi/fluid_seq.c
@@ -260,6 +260,9 @@ void fluid_seq_dotrace(fluid_sequencer_t* seq, char *fmt, ...) {}
  *
  * Clients can be sources or destinations of events.  Sources don't need to
  * register a callback.
+ * 
+ * @note The user must explicitly unregister any registered client with fluid_sequencer_unregister_client()
+ * before deleting the sequencer!
  */
 fluid_seq_id_t
 fluid_sequencer_register_client (fluid_sequencer_t* seq, const char *name,
diff --git a/src/midi/fluid_seqbind.c b/src/midi/fluid_seqbind.c
index 0248b029..20dac5d2 100644
--- a/src/midi/fluid_seqbind.c
+++ b/src/midi/fluid_seqbind.c
@@ -71,6 +71,27 @@ delete_fluid_seqbind(fluid_seqbind_t* seqbind)
 /** 
  * Registers a synthesizer as a destination client of the given sequencer.
  * The \a synth is registered with the name "fluidsynth".
+ * 
+ * @warning Due to internal memory allocation, the user must explicitly unregister
+ * the client by sending a fluid_event_unregistering(). Otherwise the behaviour is 
+ * undefined after either \p seq or \p synth is destroyed.
+@code{.cpp}
+fluid_seq_id_t seqid = fluid_sequencer_register_fluidsynth(seq, synth);
+
+// ... do work
+
+fluid_event_t* evt = new_fluid_event();
+fluid_event_set_source(evt, -1);
+fluid_event_set_dest(evt, seqid);
+fluid_event_unregistering(evt);
+
+// unregister the "fluidsynth" client immediately
+fluid_sequencer_send_now(seq, evt);
+delete_fluid_event(evt);
+delete_fluid_synth(synth);
+delete_fluid_sequencer(seq);
+@endcode
+ * 
  * @param seq Sequencer instance
  * @param synth Synthesizer instance
  * @returns Sequencer client ID, or #FLUID_FAILED on error.