Update API docs about synthesis context

doc/fluidsynth-v20-devdoc.txt

@@ -30,21 +30,22 @@ All the source code examples in this document are in the public domain; you can
 - \ref NewIn2_0_3
 - \ref NewIn2_0_2
 - \ref NewIn2_0_0
-- \ref CreatingSettings 
-- \ref CreatingSynth 
-- \ref CreatingAudioDriver 
-- \ref UsingSynth 
-- \ref LoadingSoundfonts 
+- \ref CreatingSettings
+- \ref CreatingSynth
+- \ref CreatingAudioDriver
+- \ref UsingSynth
+- \ref LoadingSoundfonts
 - \ref SendingMIDI
 - \ref RealtimeMIDI
 - \ref MIDIPlayer
 - \ref FileRenderer
 - \ref MIDIPlayerMem
-- \ref MIDIRouter 
+- \ref MIDIRouter
 - \ref Sequencer
 - \ref Shell
 - \ref Multi-channel
-- \ref Advanced 
+- \ref synth-context
+- \ref Advanced
 
 \section Disclaimer
 
@@ -735,12 +736,31 @@ int main(void) {
 
 \section Shell Shell interface
 
-The shell interface allows you to send simple textual commands to the synthesizer, to parse a command file, or to read commands from the stdin or other input streams. To find the list of currently supported commands, please check the fluid_cmd.c file or type "help" in the fluidsynth command line shell. For a full list of available <strong>command line settings</strong>, please refer to <a href="fluidsettings.xml" target="_blank"><b>FluidSettings Documentation</b></a>.
+The shell interface allows you to send simple textual commands to the synthesizer, to parse a command file, or to read commands from the stdin or other input streams. To find the list of currently supported commands, type @c help in the fluidsynth command line shell. For a full list of available <strong>command line settings</strong>, please refer to <a href="fluidsettings.xml#shell.prompt" target="_blank"><b>FluidSettings Documentation</b></a>.
 
 \section Multi-channel Multi-Channel audio rendering
 
 FluidSynth is capable of rendering all audio and all effects from all MIDI channels to separate stero buffers. Refer to the documentation of fluid_synth_process() and review the different use-cases in the example file for information on how to do that: \ref fluidsynth_process.c
 
+\section synth-context Understanding the "synthesis context"
+
+When reading through the functions exposed via our API, you will often read the note: "May or may not be called from synthesis context."
+
+The reason for this is that some functions are intentionally not thread-safe. Or they require to be called from this context to behave correctly.
+
+FluidSynth's rendering engine is implemented by using the "Dispatcher Thread Pattern". This means that a certain thread @c A which calls one of FluidSynth's rendering functions, namely
+
+- fluid_synth_process()
+- fluid_synth_nwrite_float()
+- fluid_synth_write_float()
+- fluid_synth_write_s16()
+
+automatically becomes the "synthesis thread". The terms "synthesis context" and "synthesis thread" are equivalent. A few locations in our API provide hooks that allow you to interfere this "synthesis context". At those locations you can register your own custom functions that will always be called by thread @c A. For this use-case, the following functions are of interest:
+
+- new_fluid_audio_driver2()
+- fluid_player_set_playback_callback()
+- fluid_sequencer_register_client()
+
 \section Advanced Advanced features, not yet documented.  API reference may contain more info.
 
 - Accessing low-level voice parameters

src/drivers/fluid_adriver.c

@@ -340,7 +340,8 @@ new_fluid_audio_driver(fluid_settings_t *settings, fluid_synth_t *synth)
  *
  * @note Not as efficient as new_fluid_audio_driver().
  *
- * @note As soon as an audio driver is created, the \p synth starts rendering audio.
+ * @note As soon as an audio driver is created, a new thread is spawned starting to make
+ * callbacks to \p func.
  * This means that all necessary sound-setup should be completed after this point,
  * thus of all object types in use (synth, midi player, sequencer, etc.) the audio
  * driver should always be the last one to be created and the first one to be deleted!

src/midi/fluid_seqbind.c

@@ -73,7 +73,10 @@ 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".
+ *
+ * A convenience wrapper function around fluid_sequencer_register_client(), that allows you to
+ * easily process and render enqueued sequencer events with fluidsynth's synthesizer.
+ * The client being registered will be named @c fluidsynth.
  *
  * @note Implementations are encouraged to explicitly unregister this client either by calling
  * fluid_sequencer_unregister_client() or by sending an unregistering event to the sequencer. Before