| #ifndef HEADER_CURL_BUFQ_H |
| #define HEADER_CURL_BUFQ_H |
| /*************************************************************************** |
| * _ _ ____ _ |
| * Project ___| | | | _ \| | |
| * / __| | | | |_) | | |
| * | (__| |_| | _ <| |___ |
| * \___|\___/|_| \_\_____| |
| * |
| * Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. |
| * |
| * This software is licensed as described in the file COPYING, which |
| * you should have received as part of this distribution. The terms |
| * are also available at https://curl.se/docs/copyright.html. |
| * |
| * You may opt to use, copy, modify, merge, publish, distribute and/or sell |
| * copies of the Software, and permit persons to whom the Software is |
| * furnished to do so, under the terms of the COPYING file. |
| * |
| * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY |
| * KIND, either express or implied. |
| * |
| * SPDX-License-Identifier: curl |
| * |
| ***************************************************************************/ |
| #include "curl_setup.h" |
| |
| #include <curl/curl.h> |
| |
| /** |
| * A chunk of bytes for reading and writing. |
| * The size is fixed a creation with read and write offset |
| * for where unread content is. |
| */ |
| struct buf_chunk { |
| struct buf_chunk *next; /* to keep it in a list */ |
| size_t dlen; /* the amount of allocated x.data[] */ |
| size_t r_offset; /* first unread bytes */ |
| size_t w_offset; /* one after last written byte */ |
| union { |
| unsigned char data[1]; /* the buffer for `dlen` bytes */ |
| void *dummy; /* alignment */ |
| } x; |
| }; |
| |
| /** |
| * A pool for providing/keeping a number of chunks of the same size |
| * |
| * The same pool can be shared by many `bufq` instances. However, a pool |
| * is not thread safe. All bufqs using it are supposed to operate in the |
| * same thread. |
| */ |
| struct bufc_pool { |
| struct buf_chunk *spare; /* list of available spare chunks */ |
| size_t chunk_size; /* the size of chunks in this pool */ |
| size_t spare_count; /* current number of spare chunks in list */ |
| size_t spare_max; /* max number of spares to keep */ |
| }; |
| |
| void Curl_bufcp_init(struct bufc_pool *pool, |
| size_t chunk_size, size_t spare_max); |
| |
| void Curl_bufcp_free(struct bufc_pool *pool); |
| |
| /** |
| * A queue of byte chunks for reading and writing. |
| * Reading is done from `head`, writing is done to `tail`. |
| * |
| * `bufq`s can be empty or full or neither. Its `len` is the number |
| * of bytes that can be read. For an empty bufq, `len` will be 0. |
| * |
| * By default, a bufq can hold up to `max_chunks * chunk_size` number |
| * of bytes. When `max_chunks` are used (in the `head` list) and the |
| * `tail` chunk is full, the bufq will report that it is full. |
| * |
| * On a full bufq, `len` may be less than the maximum number of bytes, |
| * e.g. when the head chunk is partially read. `len` may also become |
| * larger than the max when option `BUFQ_OPT_SOFT_LIMIT` is used. |
| * |
| * By default, writing to a full bufq will return (-1, CURLE_AGAIN). Same |
| * as reading from an empty bufq. |
| * With `BUFQ_OPT_SOFT_LIMIT` set, a bufq will allow writing becond this |
| * limit and use more than `max_chunks`. However it will report that it |
| * is full nevertheless. This is provided for situation where writes |
| * preferably never fail (except for memory exhaustion). |
| * |
| * By default and without a pool, a bufq will keep chunks that read |
| * read empty in its `spare` list. Option `BUFQ_OPT_NO_SPARES` will |
| * disable that and free chunks once they become empty. |
| * |
| * When providing a pool to a bufq, all chunk creation and spare handling |
| * will be delegated to that pool. |
| */ |
| struct bufq { |
| struct buf_chunk *head; /* chunk with bytes to read from */ |
| struct buf_chunk *tail; /* chunk to write to */ |
| struct buf_chunk *spare; /* list of free chunks, unless `pool` */ |
| struct bufc_pool *pool; /* optional pool for free chunks */ |
| size_t chunk_count; /* current number of chunks in `head+spare` */ |
| size_t max_chunks; /* max `head` chunks to use */ |
| size_t chunk_size; /* size of chunks to manage */ |
| int opts; /* options for handling queue, see below */ |
| }; |
| |
| /** |
| * Default behaviour: chunk limit is "hard", meaning attempts to write |
| * more bytes than can be hold in `max_chunks` is refused and will return |
| * -1, CURLE_AGAIN. */ |
| #define BUFQ_OPT_NONE (0) |
| /** |
| * Make `max_chunks` a "soft" limit. A bufq will report that it is "full" |
| * when `max_chunks` are used, but allows writing beyond this limit. |
| */ |
| #define BUFQ_OPT_SOFT_LIMIT (1 << 0) |
| /** |
| * Do not keep spare chunks. |
| */ |
| #define BUFQ_OPT_NO_SPARES (1 << 1) |
| |
| /** |
| * Initialize a buffer queue that can hold up to `max_chunks` buffers |
| * each of size `chunk_size`. The bufq will not allow writing of |
| * more bytes than can be held in `max_chunks`. |
| */ |
| void Curl_bufq_init(struct bufq *q, size_t chunk_size, size_t max_chunks); |
| |
| /** |
| * Initialize a buffer queue that can hold up to `max_chunks` buffers |
| * each of size `chunk_size` with the given options. See `BUFQ_OPT_*`. |
| */ |
| void Curl_bufq_init2(struct bufq *q, size_t chunk_size, |
| size_t max_chunks, int opts); |
| |
| void Curl_bufq_initp(struct bufq *q, struct bufc_pool *pool, |
| size_t max_chunks, int opts); |
| |
| /** |
| * Reset the buffer queue to be empty. Will keep any allocated buffer |
| * chunks around. |
| */ |
| void Curl_bufq_reset(struct bufq *q); |
| |
| /** |
| * Free all resources held by the buffer queue. |
| */ |
| void Curl_bufq_free(struct bufq *q); |
| |
| /** |
| * Return the total amount of data in the queue. |
| */ |
| size_t Curl_bufq_len(const struct bufq *q); |
| |
| /** |
| * Return the total amount of free space in the queue. |
| * The returned length is the number of bytes that can |
| * be expected to be written successfully to the bufq, |
| * providing no memory allocations fail. |
| */ |
| size_t Curl_bufq_space(const struct bufq *q); |
| |
| /** |
| * Returns TRUE iff there is no data in the buffer queue. |
| */ |
| bool Curl_bufq_is_empty(const struct bufq *q); |
| |
| /** |
| * Returns TRUE iff there is no space left in the buffer queue. |
| */ |
| bool Curl_bufq_is_full(const struct bufq *q); |
| |
| /** |
| * Write buf to the end of the buffer queue. The buf is copied |
| * and the amount of copied bytes is returned. |
| * A return code of -1 indicates an error, setting `err` to the |
| * cause. An err of CURLE_AGAIN is returned if the buffer queue is full. |
| */ |
| ssize_t Curl_bufq_write(struct bufq *q, |
| const unsigned char *buf, size_t len, |
| CURLcode *err); |
| |
| CURLcode Curl_bufq_cwrite(struct bufq *q, |
| const char *buf, size_t len, |
| size_t *pnwritten); |
| |
| /** |
| * Read buf from the start of the buffer queue. The buf is copied |
| * and the amount of copied bytes is returned. |
| * A return code of -1 indicates an error, setting `err` to the |
| * cause. An err of CURLE_AGAIN is returned if the buffer queue is empty. |
| */ |
| ssize_t Curl_bufq_read(struct bufq *q, unsigned char *buf, size_t len, |
| CURLcode *err); |
| |
| CURLcode Curl_bufq_cread(struct bufq *q, char *buf, size_t len, |
| size_t *pnread); |
| |
| /** |
| * Peek at the head chunk in the buffer queue. Returns a pointer to |
| * the chunk buf (at the current offset) and its length. Does not |
| * modify the buffer queue. |
| * Returns TRUE iff bytes are available. Sets `pbuf` to NULL and `plen` |
| * to 0 when no bytes are available. |
| * Repeated calls return the same information until the buffer queue |
| * is modified, see `Curl_bufq_skip()`` |
| */ |
| bool Curl_bufq_peek(struct bufq *q, |
| const unsigned char **pbuf, size_t *plen); |
| |
| bool Curl_bufq_peek_at(struct bufq *q, size_t offset, |
| const unsigned char **pbuf, size_t *plen); |
| |
| /** |
| * Tell the buffer queue to discard `amount` buf bytes at the head |
| * of the queue. Skipping more buf than is currently buffered will |
| * just empty the queue. |
| */ |
| void Curl_bufq_skip(struct bufq *q, size_t amount); |
| |
| typedef ssize_t Curl_bufq_writer(void *writer_ctx, |
| const unsigned char *buf, size_t len, |
| CURLcode *err); |
| /** |
| * Passes the chunks in the buffer queue to the writer and returns |
| * the amount of buf written. A writer may return -1 and CURLE_AGAIN |
| * to indicate blocking at which point the queue will stop and return |
| * the amount of buf passed so far. |
| * -1 is returned on any other errors reported by the writer. |
| * Note that in case of a -1 chunks may have been written and |
| * the buffer queue will have different length than before. |
| */ |
| ssize_t Curl_bufq_pass(struct bufq *q, Curl_bufq_writer *writer, |
| void *writer_ctx, CURLcode *err); |
| |
| typedef ssize_t Curl_bufq_reader(void *reader_ctx, |
| unsigned char *buf, size_t len, |
| CURLcode *err); |
| |
| /** |
| * Read date and append it to the end of the buffer queue until the |
| * reader returns blocking or the queue is full. A reader returns |
| * -1 and CURLE_AGAIN to indicate blocking. |
| * Returns the total amount of buf read (may be 0) or -1 on other |
| * reader errors. |
| * Note that in case of a -1 chunks may have been read and |
| * the buffer queue will have different length than before. |
| */ |
| ssize_t Curl_bufq_slurp(struct bufq *q, Curl_bufq_reader *reader, |
| void *reader_ctx, CURLcode *err); |
| |
| /** |
| * Read *once* up to `max_len` bytes and append it to the buffer. |
| * if `max_len` is 0, no limit is imposed besides the chunk space. |
| * Returns the total amount of buf read (may be 0) or -1 on other |
| * reader errors. |
| */ |
| ssize_t Curl_bufq_sipn(struct bufq *q, size_t max_len, |
| Curl_bufq_reader *reader, void *reader_ctx, |
| CURLcode *err); |
| |
| /** |
| * Write buf to the end of the buffer queue. |
| * Will write bufq content or passed `buf` directly using the `writer` |
| * callback when it sees fit. 'buf' might get passed directly |
| * on or is placed into the buffer, depending on `len` and current |
| * amount buffered, chunk size, etc. |
| */ |
| ssize_t Curl_bufq_write_pass(struct bufq *q, |
| const unsigned char *buf, size_t len, |
| Curl_bufq_writer *writer, void *writer_ctx, |
| CURLcode *err); |
| |
| #endif /* HEADER_CURL_BUFQ_H */ |
