From c2318e55f6715d474dd61243b987eddd05358cf7 Mon Sep 17 00:00:00 2001 From: Nicolas Dato Date: Sat, 19 Jul 2025 19:15:50 -0300 Subject: text wrap at 80 characters --- README.md | 33 +++++++++++++++++++-- src/tuberia.h | 94 +++++++++++++++++++++++++++++++++++++---------------------- 2 files changed, 90 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index ebe3c4d..82f3ccb 100644 --- a/README.md +++ b/README.md @@ -6,9 +6,11 @@ A pipeline would be: *[Source] -> [queue_1] -> [Stage_1] -> [Queue_2] -> [Stage_2] -> [...] -> [Sink]* -Each source, stage, and sink runs in a thread, reads from its imput queue and write to the output queue +Each source, stage, and sink runs in a thread, reads from its imput queue and +write to the output queue -You can ommit the source and sink, and inject or retrive elements from the pipelie +You can ommit the source and sink, and inject or retrive elements from the +pipeline ## Building, Compiling, Installing @@ -25,5 +27,32 @@ You can see some configuration options with: ## Quick Guide +See the `example/decode_resize_encode.c` and the function `do_tuberia()` + +Create a source with `tube_source_alloc()`. +If you set fetch to something, there will be a thread running fetch to inject +elements into the pipeline. +If you set fetch to NULL, you have to inject the elements with `tube_inject()`. + +Create as many stages as you need with `tube_stage_alloc()`, and append them +to the source with `tube_stage_append()`. + +Build the pipeline with `tube_alloc()`. If you set sink to something, +there will be a thread running sink to get the elements from the pipeline. +If you set sink to NULL, you have to retrieve the elements with +`tube_retrieve()`. + +The `tube_alloc()` function copies the source and all the appended stages, +so you can free the source and stages with `tube_source_and_stages_free()`. +Or, you can reutilize the same `tube_source` to build more pipelines. + +Start the pipeline with `tube_start()`. + +Free the pipeline with `tube_free()`. + + ### Quick example +```C + +``` diff --git a/src/tuberia.h b/src/tuberia.h index e965840..f9746b2 100644 --- a/src/tuberia.h +++ b/src/tuberia.h @@ -16,7 +16,8 @@ * Each source, stage, and sink runs in a thread, reads from its input queue and * write to the output queue. * - * You can omit the source and/or sink, and inject and/or retrieve elements from the pipeline. + * You can omit the source and/or sink, and inject and/or retrieve elements from + * the pipeline. * * @section building Building * @@ -38,18 +39,19 @@ * Create a source with @ref tube_source_alloc(). * If you set fetch to something, there will be a thread running fetch to inject * elements into the pipeline. - * If you set fetch to NULL, you have to inject the elements with @ref tube_inject(). + * If you set fetch to NULL, you have to inject elements with @ref tube_inject(). * - * Create as many stages as you need with @ref tube_stage_alloc(), and append them - * to the source with @ref tube_stage_append(). + * Create as many stages as you need with @ref tube_stage_alloc(), and append + * them to the source with @ref tube_stage_append(). * * Build the pipeline with @ref tube_alloc(). If you set sink to something, * there will be a thread running sink to get the elements from the pipeline. - * If you set sink to NULL, you have to retrieve the elements with @ref tube_retrieve(). + * If you set sink to NULL, you have to retrieve the elements + * with @ref tube_retrieve(). * * The @ref tube_alloc() function copies the source and all the appended stages, - * so you can free the source and stages with @ref tube_source_and_stages_free(). - * Or, you can reutilize the same tube_source to build more pipelines. + * so the source and stages can be freed with @ref tube_source_and_stages_free(). + * Or, you can reutilize the same @ref tube_source to build more pipelines. * * Start the pipeline with @ref tube_start(). * @@ -144,7 +146,8 @@ typedef void (*tube_free_element)(void *element); * the next stage. If the queue is full, the source will block * @param fetch A function to generate a new element. A thread will run and call * this function to get the new element and put it in the queue. - * If this is NULL, you have to insert the elements with @ref tube_inject(). + * If this is NULL, you have to insert the elements + * with @ref tube_inject(). * @param opaque A data pointer passed to the fetch function. * @param free_element A function to free the elements generated by the fetch * function, or inserted with @ref tube_inject(). @@ -153,12 +156,15 @@ typedef void (*tube_free_element)(void *element); * * @see tube_source_and_stages_free() */ -tube_source *tube_source_alloc(int nslots, tube_fetch fetch, void *opaque, tube_free_element free_element); +tube_source *tube_source_alloc(int nslots, tube_fetch fetch, void *opaque, + tube_free_element free_element); /** - * Allocates a source, a function to receive an element, process it, and send it to the next stage. + * Allocates a source, a function to receive an element, process it, and send it + * to the next stage. * - * Free it with @ref tube_source_and_stages_free(), unless it was never appended then you free it with @ref tube_stage_free() + * Free it with @ref tube_source_and_stages_free(), unless it was never appended + * then you free it with @ref tube_stage_free(). * * @param nslots Number of slots available in the queue between this stage and * the next stage. If the queue is full, the stage will block. @@ -171,7 +177,8 @@ tube_source *tube_source_alloc(int nslots, tube_fetch fetch, void *opaque, tube_ * * @see tube_stage_append(), tube_source_and_stages_free(), tube_stage_free() */ -tube_stage *tube_stage_alloc(int nslots, tube_process process, void *opaque, tube_free_element free_element); +tube_stage *tube_stage_alloc(int nslots, tube_process process, void *opaque, + tube_free_element free_element); /** * Frees an stage and sets the pointer to NULL @@ -204,7 +211,8 @@ void tube_source_and_stages_free(tube_source **source); * @note The owner of the stage pointer will be the source. Don't use it anymore. * * @param source The source to append the stage. - * @param stage The stage to be appended to the source. The source will become the owner of this pointer. + * @param stage The stage to be appended to the source. The source will become + * the owner of this pointer. * * @return 0 if OK, less than 0 in case of error. */ @@ -219,7 +227,8 @@ int tube_stage_append(tube_source *source, tube_stage *stage); * The pipeline won't start until you call @ref tube_start(). * * @param source The source with all the stages appended - * @param sink A function to receive the last element from the pipeline. If this is NULL, you have to use @ref tube_retrieve(). + * @param sink A function to receive the last element from the pipeline. + * If this is NULL, you have to use @ref tube_retrieve(). * @param opaque A data pointer passed to the sink function. * * @return The pipeline, or NULL in case of error @@ -231,7 +240,9 @@ tube *tube_alloc(const tube_source *source, tube_sink sink, void *opaque); /** * Starts the pipeline. * - * This will start the threads to read from queues, process the elements, and write to queues the result. Can be stopped with @ref tube_stop() or @ref tube_stop_and_wait_empty(). + * This will start the threads to read from queues, process the elements, and + * write to queues the result. + * Can be stopped with @ref tube_stop() or @ref tube_stop_and_wait_empty(). * * @param ctx The pipeline to be started * @@ -245,7 +256,9 @@ int tube_start(tube *ctx); * Stops the pipeline. * * This will stop the threads. Can be resumed later with @ref tube_start(). - * This won't flush the queues, if there are pending elements they will still be in the queues. Use @ref tube_stop_and_wait_empty() to stop and flush the queues. + * This won't flush the queues, if there are pending elements they will still be + * in the queues. + * Use @ref tube_stop_and_wait_empty() to stop and flush the queues. * * @param ctx The pipeline to be stopped * @@ -270,15 +283,15 @@ void tube_free(tube **ctx); * Insert an element to the first stage. * * Use this function if you set NULL to the source at @ref tube_source_alloc(). - * You can call this if the source is not NULL, i.e. if there is a thread running - * @ref tube_source, but be aware that the element will be inserted out of order, - * if that's important for the pipeline. + * You can call this if the source is not NULL, i.e. if there is a thread + * running @ref tube_source, but be aware that the element will be inserted out + * of order, if that's important for the pipeline. * - * @param ctx The pipeline where to insert the element - * @param timeout_ms A timeout in milliseconds, can be 0 to return without blocking - * @param element The element to be inserted into the pipeline. Can't be NULL + * @param ctx The pipeline where to insert the element + * @param timeout_ms A timeout in milliseconds, use 0 to return without blocking + * @param element The element to be inserted into the pipeline. Can't be NULL * - * @return 0 if OK, less than 0 if the timeout is reached or if there is an error + * @return 0 if OK, less than 0 if timeout is reached or if there is an error * * @see tube_inject_at(), tube_retrieve() */ @@ -289,14 +302,19 @@ int tube_inject(tube *ctx, int timeout_ms, void *element); * * If stage is 0, this is equivalent to calling @ref tube_inject(). * - * @warning This will insert an out of order element. Use this function if the order of the element inserted is not important. + * @warning This will insert an out of order element. Use this function if the + * order of the element inserted is not important. * - * @param ctx The pipeline where to insert the element - * @param timeout_ms A timeout in milliseconds, can be 0 to return without blocking - * @param stage The 0-based stage that will process this element. If there are 2 stages, stage = 0 means the element will be inserted to the input queue of the first stage, stage = 1 means the input queue of the second stage, and stage = 3 means the input queue of the sink. - * @param element The element to be inserted into the pipeline. Can't be NULL + * @param ctx The pipeline where to insert the element. + * @param timeout_ms A timeout in milliseconds, use 0 to return without blocking. + * @param stage The 0-based stage that will process this element. + * If there are 2 stages, stage = 0 means the element will be + * inserted to the input queue of the first stage, + * stage = 1 means the input queue of the second stage, + * and stage = 3 means the input queue of the sink. + * @param element The element to be inserted into the pipeline. Can't be NULL * - * @return 0 if OK, less than 0 if the timeout is reached or if there is an error + * @return 0 if OK, less than 0 if timeout is reached or if there is an error * * @see tube_inject(), tube_retrieve() */ @@ -310,8 +328,8 @@ int tube_inject_at(tube *ctx, int stage, int timeout_ms, void *element); * @ref tube_sink, but be aware that the element will be removed out of order, * if that's important for the pipeline. * - * @param ctx The pipeline from where to get the element - * @param timeout_ms A timeout in milliseconds, can be 0 to return without blocking + * @param ctx The pipeline from where to get the element + * @param timeout_ms A timeout in milliseconds, use 0 to return without blocking * * @return The element, NULL if timeout is reached or if there is an error * @@ -340,8 +358,11 @@ void tube_discard_all(tube *ctx); /** * Returns the number of queued elements at a stage. * - * @param ctx The pipeline - * @param stage The 0-based stage. If there are 2 stages, stage = 0 means the elements queued for the first stage, stage = 1 means the elements queued for the second stage, and stage = 3 means the elements queued for the sink. + * @param ctx The pipeline + * @param stage The 0-based stage. If there are 2 stages, + * stage = 0 means the elements queued for the first stage, + * stage = 1 means the elements queued for the second stage, + * and stage = 3 means the elements queued for the sink. * * @return The number of queued elements */ @@ -350,8 +371,11 @@ int tube_get_queued(const tube *ctx, int stage); /** * Returns the size (slots) of the queue at a stage. * - * @param ctx The pipeline - * @param stage The 0-based stage. If there are 2 stages, stage = 0 means the queue for the first stage, stage = 1 means the queue for the second stage, and stage = 3 means the queue for the sink. + * @param ctx The pipeline + * @param stage The 0-based stage. If there are 2 stages, + * stage = 0 means the queue for the first stage, + * stage = 1 means the queue for the second stage, + * and stage = 3 means the queue for the sink. * * @return The number of slots of the queue */ -- cgit v1.2.3