| 1 | # PROCFILE |
| 2 | |
| 3 | procfile is a library for reading text data files (i.e `/proc` files) in the fastest possible way. |
| 4 | |
| 5 | ## How it works |
| 6 | |
| 7 | The library automatically adapts (through the iterations) its memory so that each file |
| 8 | is read with single `read()` call. |
| 9 | |
| 10 | Then the library splits the file into words, using the supplied separators. |
| 11 | The library also supported quoted words (i.e. strings within of which the separators are ignored). |
| 12 | |
| 13 | ### Initialization |
| 14 | |
| 15 | Initially the caller: |
| 16 | |
| 17 | - calls `procfile_open()` to open the file and allocate the structures needed. |
| 18 | |
| 19 | ### Iterations |
| 20 | |
| 21 | For each iteration, the caller: |
| 22 | |
| 23 | - calls `procfile_readall()` to read updated contents. |
| 24 | This call also rewinds (`lseek()` to 0) before reading it. |
| 25 | |
| 26 | For every file, a [BUFFER](/src/libnetdata/buffer/README.md) is used that is automatically adjusted to fit the entire |
| 27 | file contents of the file. So the file is read with a single `read()` call (providing atomicity / consistency when |
| 28 | the data are read from the kernel). |
| 29 | |
| 30 | Once the data are read, 2 arrays of pointers are updated: |
| 31 | |
| 32 | - a `words` array, pointing to each word in the data read |
| 33 | - a `lines` array, pointing to the first word for each line |
| 34 | |
| 35 | This is highly optimized. Both arrays are automatically adjusted to |
| 36 | fit all contents and are updated in a single pass on the data. |
| 37 | |
| 38 | The library provides a number of macros: |
| 39 | |
| 40 | - `procfile_lines()` returns the # of lines read |
| 41 | - `procfile_linewords()` returns the # of words in the given line |
| 42 | - `procfile_word()` returns a pointer the given word # |
| 43 | - `procfile_line()` returns a pointer to the first word of the given line # |
| 44 | - `procfile_lineword()` returns a pointer to the given word # of the given line # |
| 45 | |
| 46 | ### Cleanup |
| 47 | |
| 48 | When the caller exits: |
| 49 | |
| 50 | - calls `procfile_free()` to close the file and free all memory used. |
| 51 | |
| 52 | ### Performance |
| 53 | |
| 54 | - a **raspberry Pi 1** (the oldest single core one) can process 5.000+ `/proc` files per second. |
| 55 | - a **J1900 Celeron** processor can process 23.000+ `/proc` files per second per core. |
| 56 | |
| 57 | To achieve this kind of performance, the library tries to work in batches so that the code |
| 58 | and the data are inside the processor's caches. |
| 59 | |
| 60 | This library is extensively used in Netdata and its plugins. |
| 61 | |
| 62 |