user-client/client-pool: update function comments about event scheduling

When scheduling events, the user client should take care of free cells in
own output memory pool. The number of free cells is available via property
of ClientPool class. The number of cells consumed by event is available
via method of Event boxed structure.

This commit adds comments about it.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>

diff --git a/src/seq/client-pool.c b/src/seq/client-pool.c
index 78c3211a14dd168513f290d751e54b5131763fe2..b1e2ef599f6b6b86466d1ada2fc40d19c4603c0b 100644 (file)
--- a/src/seq/client-pool.c
+++ b/src/seq/client-pool.c
@@ -113,7 +113,9 @@ static void alsaseq_client_pool_class_init(ALSASeqClientPoolClass *klass)
     /**
      * ALSASeqClientPool:output-pool:
      *
-     * The total number of cells in memory pool for output direction.
+     * The total number of cells in memory pool for output direction. The client enqueue any event
+     * into the pool at scheduling, then the event is copied to input memory pool of destination
+     * client.
      */
     seq_client_pool_props[SEQ_CLIENT_POOL_PROP_OUTPUT_POOL] =
         g_param_spec_uint("output-pool", "output-pool",
@@ -125,7 +127,8 @@ static void alsaseq_client_pool_class_init(ALSASeqClientPoolClass *klass)
     /**
      * ALSASeqClientPool:input-pool:
      *
-     * The total number of cells in memory pool for input direction.
+     * The total number of cells in memory pool for input direction. The client dequeue any event
+     * from the pool when the event is copied from the output memory pool of source client.
      */
     seq_client_pool_props[SEQ_CLIENT_POOL_PROP_INPUT_POOL] =
         g_param_spec_uint("input-pool", "input-pool",
@@ -137,7 +140,9 @@ static void alsaseq_client_pool_class_init(ALSASeqClientPoolClass *klass)
     /**
      * ALSASeqClientPool:output-room:
      *
-     * The number of cells in memory pool for output direction to block user process.
+     * The number of cells in memory pool for output direction as threshold for writable condition
+     * at the result of poll(2). The property is useless for [class@UserClient] since it doesn't
+     * perform poll(2) to check writable or not.
      */
     seq_client_pool_props[SEQ_CLIENT_POOL_PROP_OUTPUT_ROOM] =
         g_param_spec_uint("output-room", "output-room",
@@ -150,11 +155,11 @@ static void alsaseq_client_pool_class_init(ALSASeqClientPoolClass *klass)
     /**
      * ALSASeqClientPool:output-free:
      *
-     * The free number of cells in memory pool for output direction.
+     * The current number of free cells in memory pool for output direction.
      */
     seq_client_pool_props[SEQ_CLIENT_POOL_PROP_OUTPUT_FREE] =
         g_param_spec_uint("output-free", "output-free",
-                          "The free number of cells in memory pool for output direction.",
+                          "The current number of free cells in memory pool for output direction.",
                           0, G_MAXINT,
                           0,
                           G_PARAM_READWRITE);
@@ -162,11 +167,11 @@ static void alsaseq_client_pool_class_init(ALSASeqClientPoolClass *klass)
     /**
      * ALSASeqClientPool:input-free:
      *
-     * The free number of cells in memory pool for input direction.
+     * The current number of free cells in memory pool for input direction.
      */
     seq_client_pool_props[SEQ_CLIENT_POOL_PROP_INPUT_FREE] =
         g_param_spec_uint("input-free", "input-free",
-                          "The free number of cells in memory pool for input direction.",
+                          "The current number of free cells in memory pool for input direction.",
                           0, G_MAXINT,
                           0,
                           G_PARAM_READWRITE);

diff --git a/src/seq/user-client.c b/src/seq/user-client.c
index dd9293c2beebda559a1c8def5d73a35b96fee8a2..629afacb0afbc8b004e8c6cad5da0267f9208540 100644 (file)
--- a/src/seq/user-client.c
+++ b/src/seq/user-client.c
@@ -551,7 +551,10 @@ gboolean alsaseq_user_client_get_pool(ALSASeqUserClient *self,
  *
  * Deliver the event immediately, or schedule it into memory pool of the client.
  *
- * The call of function executes `write(2)` system call for ALSA sequencer character device.
+ * The call of function executes `write(2)` system call for ALSA sequencer character device. When
+ * [property@ClientPool:output-free] is less than [method@Event.calculate_pool_consumption] and
+ * [method@UserClient.open] is called without non-blocking flag, the user process can be blocked
+ * untill enough number of cells becomes available.
  *
  * Returns: %TRUE when the overall operation finishes successfully, else %FALSE.
  */
@@ -614,7 +617,10 @@ gboolean alsaseq_user_client_schedule_event(ALSASeqUserClient *self, const ALSAS
  *
  * Deliver the events immediately, or schedule it into memory pool of the client.
  *
- * The call of function executes `write(2)` system call for ALSA sequencer character device.
+ * The call of function executes `write(2)` system call for ALSA sequencer character device. When
+ * [property@ClientPool:output-free] is less than sum of [method@Event.calculate_pool_consumption]
+ * and [method@UserClient.open] is called without non-blocking flag, the user process can be
+ * blocked untill enough number of cells becomes available.
  *
  * Returns: %TRUE when the overall operation finishes successfully, else %FALSE.
  */