From: Michal Vaner Date: Mon, 3 Nov 2008 14:08:46 +0000 (+0100) Subject: ucw docs: make the language more English X-Git-Tag: holmes-import~214 X-Git-Url: http://mj.ucw.cz/gitweb/?a=commitdiff_plain;h=d0a95d3fed9628b5c6c34269aedd785733a740b2;p=libucw.git ucw docs: make the language more English --- diff --git a/ucw/doc/generic.txt b/ucw/doc/generic.txt index 7f59ca1c..0be825a3 100644 --- a/ucw/doc/generic.txt +++ b/ucw/doc/generic.txt @@ -2,9 +2,9 @@ Generic data structures and algorithms ====================================== The C preprocessor is a very powerful tool. One handy way to use it -can be generating generic data structures and algorithms. You can find -some conventions how they are written in libUCW and hints how to use -them. +can be generating generic data structures and algorithms. Here you can +find some conventions that are used in all such generic structures in +libUCW, and also hints for use of these structures. - <> - <> @@ -19,8 +19,8 @@ General idea The idea is simple. If you have some code, you can customize it a little by preprocessor macros. You can change constants, data types it -operates on, whole expressions, or you can exclude parts of the code -from compilation. You can generate new function names using macros. +operates on, whole expressions, or you can compile parts of the code +conditionally. You can generate new function names using macros. So if you provide few macros for data types, function names and parameters and include some code using them, it gets modified by it @@ -39,14 +39,14 @@ and an indexing function, which returns a pointer to n'th element. To get an array of integers, we need to provide macro for used data type and macro that will provide prefixes for identifier names. Then we include the file. Then we could get another array with unsigned -integers, so we will do the same. +integers, so we will do the same: #define ARRAY_TYPE int - #define ARRAY_PREFIX(suffix) intarray_##suffix + #define ARRAY_PREFIX(name) intarray_##name #include #define ARRAY_TYPE uns - #define ARRAY_PREFIX(suffix) unsarray_##suffix + #define ARRAY_PREFIX(name) unsarray_##name #include This will generate the data types (presumably `intarray_t` and @@ -54,14 +54,14 @@ This will generate the data types (presumably `intarray_t` and `unsarray_index`). We can use them like anything else. Maybe the `ARRAY_PREFIX` deserves some attention. When the header file -wants to generate a name of some identifier, it uses this macro with -some suffix. Then the macro takes the suffix, adds a prefix to it and +wants to generate an identifier, it uses this macro with +some name. Then the macro takes the name, adds a prefix to it and returns the new identifier, so `ARRAY_PREFIX(t)` will generate `intarray_t` in the first case and `unsarray_t` in the second. This allows having more than one instance of the same data structure or -algorithm, because it generates different names for them. +algorithm, because it generates different identifiers for them. -Similar macro is needed for every generic header in libUCW. +A similar macro is needed for every generic header in libUCW. [[implement]] How it is implemented @@ -82,7 +82,7 @@ works, here is the `array.h` header and some description to it. #undef ARRAY_TYPE #undef ARRAY_PREFIX -There are few thinks that are worth noticing. The first two lines +There are few things that are worth noticing. The first two lines define the data type. The macro (`ARRAY_A_TYPE`) is only for convenience inside the header, since such type names can be used quite often inside the header (if it is large). diff --git a/ucw/mainloop.h b/ucw/mainloop.h index 05393681..5bd04209 100644 --- a/ucw/mainloop.h +++ b/ucw/mainloop.h @@ -86,20 +86,20 @@ void main_get_time(void); * It supports two ways of use. With the first one, you provide * low-level handlers for reading and writing (`read_handler` and * `write_handler`). They will be called every time the file descriptor - * is ready to be read or written. + * is ready to be read from or written to. * * Return non-zero if you want to get the handler called again right now (you - * handled a block of data and expect more). If you return `0`, it will + * handled a block of data and expect more). If you return `0`, the hook will * be called again in the next iteration, if it is still ready to be read/written. * * This way is suitable for listening sockets, interactive connections, where - * you need to parse everything that comes right away and similar. + * you need to parse everything that comes right away and similar cases. * * The second way is to ask mainloop to read or write a buffer of data. You * provide a `read_done` or `write_done` handler respectively and call @file_read() * or @file_write(). This is handy for data connections where you need to transfer * data between two endpoints or for binary connections where the size of message - * is known. + * is known in advance. * * It is possible to combine both methods, but it may be tricky to do it right. * @@ -149,8 +149,10 @@ enum main_file_err_cause { **/ void file_add(struct main_file *fi); /** - * Tells the mainloop the file has changed it's state. Call it whenever you + * Tells the mainloop the file has changed its state. Call it whenever you * change any of the handlers. + * + * Can be called only on active files (only the ones added by @file_add()). **/ void file_chg(struct main_file *fi); /** @@ -202,8 +204,9 @@ void file_write(struct main_file *fi, void *buf, uns len); * * The use-cases for this are mainly sockets or pipes, when: * - * - You want to drop inactive connections (no data com or go). - * - You want to enforce answer in given time (for example authentication). + * - You want to drop inactive connections (no data come or go for a given time, not + * incomplete messages). + * - You want to enforce answer in a given time (for example authentication). * - You give maximum time for a whole connection. **/ void file_set_timeout(struct main_file *fi, timestamp_t expires);