X-Git-Url: http://mj.ucw.cz/gitweb/?a=blobdiff_plain;f=ucw%2Ffastbuf.h;h=4f0d99d3190be67c6fad8ae22e4e11a46760167d;hb=06cac26f0d8895b5cb8fbe03ca96444dc4ac8d51;hp=197dc94f6f23240cace560865587e7a90df7a178;hpb=0f73a9b90ec53017512c34f7dab56be3a50d87b1;p=libucw.git diff --git a/ucw/fastbuf.h b/ucw/fastbuf.h index 197dc94f..4f0d99d3 100644 --- a/ucw/fastbuf.h +++ b/ucw/fastbuf.h @@ -129,7 +129,6 @@ * for how it works. **/ struct fastbuf { - byte is_fastbuf[0]; /* Dummy field for checking of type casts */ byte *bptr, *bstop; /* State of the buffer */ byte *buffer, *bufend; /* Start and end of the buffer */ char *name; /* File name (used for error messages) */ @@ -144,8 +143,6 @@ struct fastbuf { struct resource *res; /* The fastbuf can be tied to a resource pool */ }; -struct fastbuf *fb_tie(struct fastbuf *b); /* Tie fastbuf to a resource if there is an active pool */ - /** * Fastbuf flags */ @@ -154,13 +151,14 @@ enum fb_flags { FB_DIE_ON_EOF = 0x2, /* Most of read operations throw "fb.eof" on EOF */ }; +/** Tie a fastbuf to a resource in the current resource pool. Returns the pointer to the same fastbuf. **/ +struct fastbuf *fb_tie(struct fastbuf *b); /* Tie fastbuf to a resource if there is an active pool */ + /*** * === Fastbuf on files [[fbparam]] * * If you want to use fastbufs to access files, you can choose one of several * back-ends and set their parameters. - * - * All file fastbufs are tied to resources automatically. ***/ /** @@ -196,7 +194,7 @@ extern struct fb_params fbpar_def; /** The default `fb_params` **/ * Use @params to select the fastbuf back-end and its parameters or * pass NULL if you are fine with defaults. * - * Dies if the file does not exist. + * Raises `ucw.fb.open` if the file does not exist. **/ struct fastbuf *bopen_file(const char *name, int mode, struct fb_params *params); struct fastbuf *bopen_file_try(const char *name, int mode, struct fb_params *params); /** Like bopen_file(), but returns NULL on failure. **/ @@ -307,8 +305,6 @@ void bclose_file_helper(struct fastbuf *f, int fd, int is_temp_file); * * The `fblim` back-end reads from a file handle, but at most a given * number of bytes. This is frequently used for reading from sockets. - * - * All such fastbufs are tied to resources automatically. ***/ struct fastbuf *bopen_limited_fd(int fd, uns bufsize, uns limit); /** Create a fastbuf which reads at most @limit bytes from @fd. **/ @@ -323,8 +319,6 @@ struct fastbuf *bopen_limited_fd(int fd, uns bufsize, uns limit); /** Create a f * First, you use @fbmem_create() to create the stream and the fastbuf * used for writing to it. Then you can call @fbmem_clone_read() to get * an arbitrary number of fastbuf for reading from the stream. - * - * All in-memory fastbufs are tied to resources automatically. ***/ struct fastbuf *fbmem_create(uns blocksize); /** Create stream and return its writing fastbuf. **/ @@ -354,7 +348,7 @@ void fbbuf_init_read(struct fastbuf *f, byte *buffer, uns size, uns can_overwrit /** * Creates a write-only fastbuf which writes into a provided memory buffer. * The fastbuf structure is allocated by the caller and pointed to by @f. - * An attempt to write behind the end of the buffer dies. + * An attempt to write behind the end of the buffer causes the `ucw.fb.write` exception. * * Data are written directly into the buffer, so it is not necessary to call @bflush() * at any moment. @@ -377,8 +371,6 @@ static inline uns fbbuf_count_written(struct fastbuf *f) /** Calculates, how man * size and it is expanded to accomodate all data. * * At every moment, you can use `fastbuf->buffer` to gain access to the stream. - * - * All fastbufs of this type are tied to resources automatically. ***/ struct mempool; @@ -387,9 +379,13 @@ struct fastbuf *fbgrow_create(unsigned basic_size); /** Create the growing buffe struct fastbuf *fbgrow_create_mp(struct mempool *mp, unsigned basic_size); /** Create the growing buffer pre-allocated to @basic_size bytes. **/ void fbgrow_reset(struct fastbuf *b); /** Reset stream and prepare for writing. **/ void fbgrow_rewind(struct fastbuf *b); /** Prepare for reading (of already written data). **/ -uns fbgrow_get_buf(struct fastbuf *b, byte **buf); /** Can be used in any state of @b (for example when writing or after fbgrow_rewind()) to - return the pointer to internal buffer and its length in bytes. The returned buffer - can be invalidated by further requests. **/ + +/** + * Can be used in any state of @b (for example when writing or after + * @fbgrow_rewind()) to return the pointer to internal buffer and its length in + * bytes. The returned buffer can be invalidated by further requests. + **/ +uns fbgrow_get_buf(struct fastbuf *b, byte **buf); /*** * === Fastbuf on memory pools [[fbpool]] @@ -440,8 +436,6 @@ void *fbpool_end(struct fbpool *fb); * * Please note that initialization of the clones is not thread-safe, * so you have to serialize it yourself. - * - * The atomic fastbufs are tied to resources automatically. ***/ struct fb_atomic { @@ -450,7 +444,6 @@ struct fb_atomic { byte *expected_max_bptr; uns slack_size; }; -#define FB_ATOMIC(f) ((struct fb_atomic *)(f)->is_fastbuf) /** * Open an atomic fastbuf. @@ -480,6 +473,53 @@ static inline void fbatomic_commit(struct fastbuf *b) fbatomic_internal_write(b); } +/*** + * === Fastbufs atop other fastbufs [[fbmulti]] + * + * Imagine some code which does massive string processing. It takes an input + * buffer, writes a part of it into an output buffer, then some other string + * and then the remaining part of the input buffer. Or anything else where you + * copy all the data at each stage of the complicated process. + * + * This backend takes multiple fastbufs and concatenates them formally into + * one. You may then read them consecutively as they were one fastbuf at all. + * + * This backend is read-only. + * + * This backend is seekable iff all of the supplied fastbufs are seekable. + * + * You aren't allowed to do anything with the underlying buffers while these + * are connected into fbmulti. + * + * The fbmulti is inited by @fbmulti_create(). It returns an empty fbmulti. + * Then you call @fbmulti_append() for each fbmulti. + * + * If @bclose() is called on fbmulti, all the underlying buffers get closed + * recursively. + * + * If you want to keep an underlying fastbuf open after @bclose, just remove it + * by @fbmulti_remove where the second parameter is a pointer to the removed + * fastbuf. If you pass NULL, all the underlying fastbufs are removed. + * + * After @fbmulti_remove, the state of the fbmulti is undefined. The only allowed + * operation is either another @fbmulti_remove or @bclose on the fbmulti. + ***/ + +/** + * Create an empty fbmulti + **/ +struct fastbuf *fbmulti_create(void); + +/** + * Append a fb to fbmulti + **/ +void fbmulti_append(struct fastbuf *f, struct fastbuf *fb); + +/** + * Remove a fb from fbmulti + **/ +void fbmulti_remove(struct fastbuf *f, struct fastbuf *fb); + /*** === Configuring stream parameters [[bconfig]] ***/ enum bconfig_type { /** Parameters that could be configured. **/ @@ -573,7 +613,7 @@ static inline uns bread(struct fastbuf *f, void *b, uns l) /** * Reads exactly @l bytes of data into @b. * If at the end of file, it returns 0. - * If there are data, but less than @l, it dies. + * If there are data, but less than @l, it raises `ucw.fb.eof`. */ static inline uns breadb(struct fastbuf *f, void *b, uns l) { @@ -602,7 +642,7 @@ static inline void bwrite(struct fastbuf *f, const void *b, uns l) /** Writes bu /** * Reads a line into @b and strips trailing `\n`. * Returns pointer to the terminating 0 or NULL on `EOF`. - * Dies if the line is longer than @l. + * Raises `ucw.fb.toolong` if the line is longer than @l. **/ char *bgets(struct fastbuf *f, char *b, uns l); char *bgets0(struct fastbuf *f, char *b, uns l); /** The same as @bgets(), but for 0-terminated strings. **/ @@ -616,7 +656,7 @@ struct mempool; struct bb_t; /** * Read a string, strip the trailing `\n` and store it into growing buffer @b. - * Dies if the line is longer than @limit. + * Raises `ucw.fb.toolong` if the line is longer than @limit. **/ uns bgets_bb(struct fastbuf *f, struct bb_t *b, uns limit); /**