From 13f2539acd01e23e5fe91c5057d380cc5ad345c3 Mon Sep 17 00:00:00 2001 From: Takashi Sakamoto Date: Mon, 27 Jun 2022 17:46:54 +0900 Subject: [PATCH] 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 --- src/seq/client-pool.c | 19 ++++++++++++------- src/seq/user-client.c | 10 ++++++++-- 2 files changed, 20 insertions(+), 9 deletions(-) diff --git a/src/seq/client-pool.c b/src/seq/client-pool.c index 78c3211..b1e2ef5 100644 --- 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 dd9293c..629afac 100644 --- 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. */ -- 2.47.3