add some documentation

README.md

@@ -17,12 +17,14 @@ exposed.
    - Logs messages to stdio and you can't turn that off.
    - Does not support channel layouts / channel maps.
    - Does not support emitting an event when available devices change.
+   - Does not let you connect to multiple backends at once.
    - Not written by me.
  * [rtaudio](https://www.music.mcgill.ca/~gary/rtaudio/)
    - It is not a C library.
    - It uses [exceptions](http://stackoverflow.com/questions/1736146/why-is-exception-handling-bad).
    - It does not support channel layouts / channel maps.
    - Does not support emitting an event when available devices change.
+   - Does not let you connect to multiple backends at once.
    - Not written by me.
  * [SDL](https://www.libsdl.org/)
    - Comes with baggage: display, windowing, input handling, and lots more.
@@ -31,6 +33,7 @@ exposed.
    - Does not support recording devices.
    - Does not support channel layouts / channel maps.
    - Does not support emitting an event when available devices change.
+   - Does not let you connect to multiple backends at once.
    - Not written by me.
 
 ## How It Works

src/alsa.cpp

@@ -684,6 +684,7 @@ static int refresh_devices(SoundIoPrivate *si) {
     sia->ready_devices_info = devices_info;
     sia->have_devices_flag.store(true);
     soundio_os_cond_signal(sia->cond, sia->mutex);
+    soundio->on_events_signal(soundio);
     soundio_os_mutex_unlock(sia->mutex);
     return 0;
 }

src/soundio.h

@@ -356,14 +356,19 @@ struct SoundIoInStream {
 struct SoundIo {
     // Defaults to NULL. Put whatever you want here.
     void *userdata;
+    // Optional callback. Called when the list of devices change. Only called
+    // during a call to soundio_flush_events or soundio_wait_events.
     void (*on_devices_change)(struct SoundIo *);
+    // Optional callback. Called from an unknown thread that you should not use
+    // to call any soundio functions. You may use this to signal a condition
+    // variable to wake up. Called when soundio_wait_events would be woken up.
     void (*on_events_signal)(struct SoundIo *);
 };
 
 // Main Context
 
-// Create a SoundIo context.
-// Returns an error code.
+// Create a SoundIo context. You may create multiple instances of this to
+// connect to multiple backends.
 struct SoundIo * soundio_create(void);
 void soundio_destroy(struct SoundIo *soundio);