diff options
| -rw-r--r-- | src/nvim/memfile.c | 805 | ||||
| -rw-r--r-- | src/nvim/memfile.h | 10 | ||||
| -rw-r--r-- | src/nvim/memfile_defs.h | 137 |
3 files changed, 433 insertions, 519 deletions
diff --git a/src/nvim/memfile.c b/src/nvim/memfile.c index 827cff2299..ca6628afb1 100644 --- a/src/nvim/memfile.c +++ b/src/nvim/memfile.c @@ -1,35 +1,47 @@ /* - * VIM - Vi IMproved by Bram Moolenaar + * VIM - Vi IMproved by Bram Moolenaar * * Do ":help uganda" in Vim to read copying and usage conditions. * Do ":help credits" in Vim to see a list of people who contributed. * See README.txt for an overview of the Vim source code. */ -/* - * memfile.c: Contains the functions for handling blocks of memory which can - * be stored in a file. This is the implementation of a sort of virtual memory. - * - * A memfile consists of a sequence of blocks. The blocks numbered from 0 - * upwards have been assigned a place in the actual file. The block number - * is equal to the page number in the file. The - * blocks with negative numbers are currently in memory only. They can be - * assigned a place in the file when too much memory is being used. At that - * moment they get a new, positive, number. A list is used for translation of - * negative to positive numbers. - * - * The size of a block is a multiple of a page size, normally the page size of - * the device the file is on. Most blocks are 1 page long. A Block of multiple - * pages is used for a line that does not fit in a single page. - * - * Each block can be in memory and/or in a file. The block stays in memory - * as long as it is locked. If it is no longer locked it can be swapped out to - * the file. It is only written to the file if it has been changed. - * - * Under normal operation the file is created when opening the memory file and - * deleted when closing the memory file. Only with recovery an existing memory - * file is opened. - */ +/// An abstraction to handle blocks of memory which can be stored in a file. +/// This is the implementation of a sort of virtual memory. +/// +/// A memfile consists of a sequence of blocks: +/// - Blocks numbered from 0 upwards have been assigned a place in the actual +/// file. The block number is equal to the page number in the file. +/// - Blocks with negative numbers are currently in memory only. They can be +/// assigned a place in the file when too much memory is being used. At that +/// moment, they get a new, positive, number. A list is used for translation +/// of negative to positive numbers. +/// +/// The size of a block is a multiple of a page size, normally the page size of +/// the device the file is on. Most blocks are 1 page long. A block of multiple +/// pages is used for a line that does not fit in a single page. +/// +/// Each block can be in memory and/or in a file. The block stays in memory +/// as long as it is locked. If it is no longer locked it can be swapped out to +/// the file. It is only written to the file if it has been changed. +/// +/// Under normal operation the file is created when opening the memory file and +/// deleted when closing the memory file. Only with recovery an existing memory +/// file is opened. +/// +/// The functions for using a memfile: +/// +/// mf_open() open a new or existing memfile +/// mf_open_file() open a swap file for an existing memfile +/// mf_close() close (and delete) a memfile +/// mf_new() create a new block in a memfile and lock it +/// mf_get() get an existing block and lock it +/// mf_put() unlock a block, may be marked for writing +/// mf_free() remove a block +/// mf_sync() sync changed parts of memfile to disk +/// mf_release_all() release as much memory as possible +/// mf_trans_del() may translate negative to positive block number +/// mf_fullname() make file name full path (use before first :cd) #include <errno.h> #include <inttypes.h> @@ -49,64 +61,49 @@ #include "nvim/ui.h" #include "nvim/os/os.h" -#define MEMFILE_PAGE_SIZE 4096 /* default page size */ +#define MEMFILE_PAGE_SIZE 4096 /// default page size -static long_u total_mem_used = 0; /* total memory used for memfiles */ +static long_u total_mem_used = 0; /// total memory used for memfiles #ifdef INCLUDE_GENERATED_DECLARATIONS # include "memfile.c.generated.h" #endif -/* - * The functions for using a memfile: - * - * mf_open() open a new or existing memfile - * mf_open_file() open a swap file for an existing memfile - * mf_close() close (and delete) a memfile - * mf_new() create a new block in a memfile and lock it - * mf_get() get an existing block and lock it - * mf_put() unlock a block, may be marked for writing - * mf_free() remove a block - * mf_sync() sync changed parts of memfile to disk - * mf_release_all() release as much memory as possible - * mf_trans_del() may translate negative to positive block number - * mf_fullname() make file name full path (use before first :cd) - */ -/* - * Open an existing or new memory block file. - * - * fname: name of file to use (NULL means no file at all) - * Note: fname must have been allocated, it is not copied! - * If opening the file fails, fname is freed. - * flags: flags for open() call - * - * If fname != NULL and file cannot be opened, fail. - * - * return value: identifier for this memory block file. - */ +/// Open a new or existing memory block file. +/// +/// @param fname Name of file to use. +/// - If NULL, it means no file (use memory only). +/// - If not NULL: +/// * Should correspond to an existing file. +/// * String must have been allocated (it is not copied). +/// * If opening the file fails, it is freed and function fails. + +/// @param flags Flags for open() call. +/// +/// @return - The open memory file, on success. +/// - NULL, on failure. memfile_T *mf_open(char_u *fname, int flags) { off_t size; memfile_T *mfp = xmalloc(sizeof(memfile_T)); - if (fname == NULL) { /* no file for this memfile, use memory only */ + if (fname == NULL) { // no file, use memory only mfp->mf_fname = NULL; mfp->mf_ffname = NULL; mfp->mf_fd = -1; - } else { - mf_do_open(mfp, fname, flags); /* try to open the file */ + } else { // try to open the file + mf_do_open(mfp, fname, flags); - /* if the file cannot be opened, return here */ - if (mfp->mf_fd < 0) { + if (mfp->mf_fd < 0) { // fail if file could not be opened free(mfp); return NULL; } } - mfp->mf_free_first = NULL; /* free list is empty */ - mfp->mf_used_first = NULL; /* used list is empty */ + mfp->mf_free_first = NULL; // free list is empty + mfp->mf_used_first = NULL; // used list is empty mfp->mf_used_last = NULL; mfp->mf_dirty = FALSE; mfp->mf_used_count = 0; @@ -114,13 +111,7 @@ memfile_T *mf_open(char_u *fname, int flags) mf_hash_init(&mfp->mf_trans); mfp->mf_page_size = MEMFILE_PAGE_SIZE; - /* - * Try to set the page size equal to the block size of the device. - * Speeds up I/O a lot. - * When recovering, the actual block size will be retrieved from block 0 - * in ml_recover(). The size used here may be wrong, therefore - * mf_blocknr_max must be rounded up. - */ + // Try to set the page size equal to device's block size. Speeds up I/O a lot. FileInfo file_info; if (mfp->mf_fd >= 0 && os_fileinfo_fd(mfp->mf_fd, &file_info)) { uint64_t blocksize = os_fileinfo_blocksize(&file_info); @@ -129,9 +120,13 @@ memfile_T *mf_open(char_u *fname, int flags) } } + // When recovering, the actual block size will be retrieved from block 0 + // in ml_recover(). The size used here may be wrong, therefore mf_blocknr_max + // must be rounded up. if (mfp->mf_fd < 0 || (flags & (O_TRUNC|O_EXCL)) || (size = lseek(mfp->mf_fd, (off_t)0L, SEEK_END)) <= 0) - mfp->mf_blocknr_max = 0; /* no file or empty file */ + // no file or empty file + mfp->mf_blocknr_max = 0; else mfp->mf_blocknr_max = (blocknr_T)((size + mfp->mf_page_size - 1) / mfp->mf_page_size); @@ -139,11 +134,9 @@ memfile_T *mf_open(char_u *fname, int flags) mfp->mf_neg_count = 0; mfp->mf_infile_count = mfp->mf_blocknr_max; - /* - * Compute maximum number of pages ('maxmem' is in Kbyte): - * 'mammem' * 1Kbyte / page-size-in-bytes. - * Avoid overflow by first reducing page size as much as possible. - */ + // Compute maximum number of pages ('maxmem' is in Kbytes): + // 'mammem' * 1Kbyte / page-size-in-bytes. + // Avoid overflow by first reducing page size as much as possible. { int shift = 10; unsigned page_size = mfp->mf_page_size; @@ -152,6 +145,7 @@ memfile_T *mf_open(char_u *fname, int flags) page_size /= 2; --shift; } + mfp->mf_used_count_max = (p_mm << shift) / page_size; if (mfp->mf_used_count_max < 10) mfp->mf_used_count_max = 10; @@ -160,19 +154,22 @@ memfile_T *mf_open(char_u *fname, int flags) return mfp; } -/* - * Open a file for an existing memfile. Used when updatecount set from 0 to - * some value. - * If the file already exists, this fails. - * "fname" is the name of file to use (NULL means no file at all) - * Note: "fname" must have been allocated, it is not copied! If opening the - * file fails, "fname" is freed. - * - * return value: FAIL if file could not be opened, OK otherwise - */ +/// Open a file for an existing memfile. +/// +/// Used when updatecount set from 0 to some value. +/// +/// @param fname Name of file to use. +/// - If NULL, it means no file (use memory only). +/// - If not NULL: +/// * Should correspond to an existing file. +/// * String must have been allocated (it is not copied). +/// * If opening the file fails, it is freed and function fails. +/// +/// @return OK On success. +/// FAIL If file could not be opened. int mf_open_file(memfile_T *mfp, char_u *fname) { - mf_do_open(mfp, fname, O_RDWR|O_CREAT|O_EXCL); /* try to open the file */ + mf_do_open(mfp, fname, O_RDWR|O_CREAT|O_EXCL); // try to open the file if (mfp->mf_fd < 0) return FAIL; @@ -181,14 +178,14 @@ int mf_open_file(memfile_T *mfp, char_u *fname) return OK; } -/* - * Close a memory file and delete the associated file if 'del_file' is TRUE. - */ +/// Close a memory file and optionally delete the associated file. +/// +/// @param del_file TRUE to delete associated file. void mf_close(memfile_T *mfp, int del_file) { bhdr_T *hp, *nextp; - if (mfp == NULL) /* safety check */ + if (mfp == NULL) // safety check return; if (mfp->mf_fd >= 0) { if (close(mfp->mf_fd) < 0) @@ -196,52 +193,48 @@ void mf_close(memfile_T *mfp, int del_file) } if (del_file && mfp->mf_fname != NULL) os_remove((char *)mfp->mf_fname); - /* free entries in used list */ + // free entries in used list for (hp = mfp->mf_used_first; hp != NULL; hp = nextp) { total_mem_used -= hp->bh_page_count * mfp->mf_page_size; nextp = hp->bh_next; mf_free_bhdr(hp); } - while (mfp->mf_free_first != NULL) /* free entries in free list */ + while (mfp->mf_free_first != NULL) // free entries in free list free(mf_rem_free(mfp)); mf_hash_free(&mfp->mf_hash); - mf_hash_free_all(&mfp->mf_trans); /* free hashtable and its items */ + mf_hash_free_all(&mfp->mf_trans); // free hashtable and its items free(mfp->mf_fname); free(mfp->mf_ffname); free(mfp); } -/* - * Close the swap file for a memfile. Used when 'swapfile' is reset. - */ -void -mf_close_file ( - buf_T *buf, - int getlines /* get all lines into memory? */ -) +/// Close the swap file for a memfile. Used when 'swapfile' is reset. +/// +/// @param getlines TRUE to get all lines into memory. +void mf_close_file (buf_T *buf, int getlines) { memfile_T *mfp; linenr_T lnum; mfp = buf->b_ml.ml_mfp; - if (mfp == NULL || mfp->mf_fd < 0) /* nothing to close */ + if (mfp == NULL || mfp->mf_fd < 0) // nothing to close return; if (getlines) { - /* get all blocks in memory by accessing all lines (clumsy!) */ + // get all blocks in memory by accessing all lines (clumsy!) mf_dont_release = TRUE; for (lnum = 1; lnum <= buf->b_ml.ml_line_count; ++lnum) (void)ml_get_buf(buf, lnum, FALSE); mf_dont_release = FALSE; - /* TODO: should check if all blocks are really in core */ + // TODO: should check if all blocks are really in core } - if (close(mfp->mf_fd) < 0) /* close the file */ + if (close(mfp->mf_fd) < 0) // close the file EMSG(_(e_swapclose)); mfp->mf_fd = -1; if (mfp->mf_fname != NULL) { - os_remove((char *)mfp->mf_fname); // delete the swap file + os_remove((char *)mfp->mf_fname); // delete the swap file free(mfp->mf_fname); free(mfp->mf_ffname); mfp->mf_fname = NULL; @@ -249,53 +242,45 @@ mf_close_file ( } } -/* - * Set new size for a memfile. Used when block 0 of a swapfile has been read - * and the size it indicates differs from what was guessed. - */ +/// Set new size for a memfile. Used when block 0 of a swapfile has been read +/// and the size it indicates differs from what was guessed. void mf_new_page_size(memfile_T *mfp, unsigned new_size) { - /* Correct the memory used for block 0 to the new size, because it will be - * freed with that size later on. */ + // Correct the memory used for block 0 to the new size, because it will be + // freed with that size later on. total_mem_used += new_size - mfp->mf_page_size; mfp->mf_page_size = new_size; } -/* - * get a new block - * - * negative: TRUE if negative block number desired (data block) - */ +/// Get a new block +/// +/// @param negative TRUE if negative block number desired (data block) +/// @param page_count Desired number of pages. bhdr_T *mf_new(memfile_T *mfp, int negative, int page_count) { - bhdr_T *hp; /* new bhdr_T */ - bhdr_T *freep; /* first block in free list */ + bhdr_T *hp; // new block + bhdr_T *freep; // first block in free list char_u *p; - /* - * If we reached the maximum size for the used memory blocks, release one - * If a bhdr_T is returned, use it and adjust the page_count if necessary. - */ + // If we reached the maximum size for the used memory blocks, release one. + // If a bhdr_T is returned, use it and adjust the page_count if necessary. + // If no bhdr_T is returned, a new one will be created. hp = mf_release(mfp, page_count); - /* - * Decide on the number to use: - * If there is a free block, use its number. - * Otherwise use mf_block_min for a negative number, mf_block_max for - * a positive number. - */ + // Decide on the number to use: + // If there is a free block, use its number. + // Otherwise use mf_block_min for a negative number, mf_block_max for + // a positive number. freep = mfp->mf_free_first; if (!negative && freep != NULL && freep->bh_page_count >= page_count) { - /* - * If the block in the free list has more pages, take only the number - * of pages needed and allocate a new bhdr_T with data - * - * If the number of pages matches and mf_release() did not return a - * bhdr_T, use the bhdr_T from the free list and allocate the data - * - * If the number of pages matches and mf_release() returned a bhdr_T, - * just use the number and free the bhdr_T from the free list - */ + // If the block in the free list has more pages, take only the number + // of pages needed and allocate a new bhdr_T with data. + // + // If the number of pages matches and mf_release() did not return a + // bhdr_T, use the bhdr_T from the free list and allocate the data. + // + // If the number of pages matches and mf_release() returned a bhdr_T, + // just use the number and free the bhdr_T from the free list if (freep->bh_page_count > page_count) { if (hp == NULL) { hp = mf_alloc_bhdr(mfp, page_count); @@ -303,16 +288,16 @@ bhdr_T *mf_new(memfile_T *mfp, int negative, int page_count) hp->bh_bnum = freep->bh_bnum; freep->bh_bnum += page_count; freep->bh_page_count -= page_count; - } else if (hp == NULL) { /* need to allocate memory for this block */ + } else if (hp == NULL) { // need to allocate memory for this block p = xmalloc(mfp->mf_page_size * page_count); hp = mf_rem_free(mfp); hp->bh_data = p; - } else { /* use the number, remove entry from free list */ + } else { // use the number, remove entry from free list freep = mf_rem_free(mfp); hp->bh_bnum = freep->bh_bnum; free(freep); } - } else { /* get a new number */ + } else { // get a new number if (hp == NULL) { hp = mf_alloc_bhdr(mfp, page_count); } @@ -324,49 +309,43 @@ bhdr_T *mf_new(memfile_T *mfp, int negative, int page_count) mfp->mf_blocknr_max += page_count; } } - hp->bh_flags = BH_LOCKED | BH_DIRTY; /* new block is always dirty */ + hp->bh_flags = BH_LOCKED | BH_DIRTY; // new block is always dirty mfp->mf_dirty = TRUE; hp->bh_page_count = page_count; mf_ins_used(mfp, hp); mf_ins_hash(mfp, hp); - /* - * Init the data to all zero, to avoid reading uninitialized data. - * This also avoids that the passwd file ends up in the swap file! - */ + // Init the data to all zero, to avoid reading uninitialized data. + // This also avoids that the passwd file ends up in the swap file! (void)memset((char *)(hp->bh_data), 0, (size_t)mfp->mf_page_size * page_count); return hp; } -/* - * Get existing block "nr" with "page_count" pages. - * - * Note: The caller should first check a negative nr with mf_trans_del() - */ +// Get existing block "nr" with "page_count" pages. +// +// Caller should first check a negative nr with mf_trans_del(). +// +// @return NULL if not found bhdr_T *mf_get(memfile_T *mfp, blocknr_T nr, int page_count) { bhdr_T *hp; - /* doesn't exist */ + // check block number exists if (nr >= mfp->mf_blocknr_max || nr <= mfp->mf_blocknr_min) return NULL; - /* - * see if it is in the cache - */ + // see if it is in the cache hp = mf_find_hash(mfp, nr); - if (hp == NULL) { /* not in the hash list */ - if (nr < 0 || nr >= mfp->mf_infile_count) /* can't be in the file */ + if (hp == NULL) { // not in the hash list + if (nr < 0 || nr >= mfp->mf_infile_count) // can't be in the file return NULL; - /* could check here if the block is in the free list */ + // could check here if the block is in the free list - /* - * Check if we need to flush an existing block. - * If so, use that block. - * If not, allocate a new block. - */ + // Check if we need to flush an existing block. + // If so, use that block. + // If not, allocate a new block. hp = mf_release(mfp, page_count); if (hp == NULL) { hp = mf_alloc_bhdr(mfp, page_count); @@ -375,30 +354,26 @@ bhdr_T *mf_get(memfile_T *mfp, blocknr_T nr, int page_count) hp->bh_bnum = nr; hp->bh_flags = 0; hp->bh_page_count = page_count; - if (mf_read(mfp, hp) == FAIL) { /* cannot read the block! */ + if (mf_read(mfp, hp) == FAIL) { // cannot read the block mf_free_bhdr(hp); return NULL; } } else { - mf_rem_used(mfp, hp); /* remove from list, insert in front below */ + mf_rem_used(mfp, hp); // remove from list, insert in front below mf_rem_hash(mfp, hp); } hp->bh_flags |= BH_LOCKED; - mf_ins_used(mfp, hp); /* put in front of used list */ - mf_ins_hash(mfp, hp); /* put in front of hash list */ + mf_ins_used(mfp, hp); // put in front of used list + mf_ins_hash(mfp, hp); // put in front of hash list return hp; } -/* - * release the block *hp - * - * dirty: Block must be written to file later - * infile: Block should be in file (needed for recovery) - * - * no return value, function cannot fail - */ +/// Release the block *hp. +/// +/// @param dirty Block must be written to file later. +/// @param infile Block should be in file (needed for recovery). void mf_put(memfile_T *mfp, bhdr_T *hp, int dirty, int infile) { int flags; @@ -414,37 +389,36 @@ void mf_put(memfile_T *mfp, bhdr_T *hp, int dirty, int infile) } hp->bh_flags = flags; if (infile) - mf_trans_add(mfp, hp); /* may translate negative in positive nr */ + mf_trans_add(mfp, hp); // may translate negative in positive nr } -/* - * block *hp is no longer in used, may put it in the free list of memfile *mfp - */ +/// Signal block as no longer used (may put it in the free list). void mf_free(memfile_T *mfp, bhdr_T *hp) { - free(hp->bh_data); /* free the memory */ - mf_rem_hash(mfp, hp); /* get *hp out of the hash list */ - mf_rem_used(mfp, hp); /* get *hp out of the used list */ + free(hp->bh_data); // free data + mf_rem_hash(mfp, hp); // get *hp out of the hash list + mf_rem_used(mfp, hp); // get *hp out of the used list if (hp->bh_bnum < 0) { - free(hp); /* don't want negative numbers in free list */ + free(hp); // don't want negative numbers in free list mfp->mf_neg_count--; } else - mf_ins_free(mfp, hp); /* put *hp in the free list */ + mf_ins_free(mfp, hp); // put *hp in the free list } -/* - * Sync the memory file *mfp to disk. - * Flags: - * MFS_ALL If not given, blocks with negative numbers are not synced, - * even when they are dirty! - * MFS_STOP Stop syncing when a character becomes available, but sync at - * least one block. - * MFS_FLUSH Make sure buffers are flushed to disk, so they will survive a - * system crash. - * MFS_ZERO Only write block 0. - * - * Return FAIL for failure, OK otherwise - */ +/// Sync memory file to disk. +/// +/// @param flags MFS_ALL If not given, blocks with negative numbers are not +/// synced, even when they are dirty. +/// MFS_STOP Stop syncing when a character becomes available, +/// but sync at least one block. +/// MFS_FLUSH Make sure buffers are flushed to disk, so they will +/// survive a system crash. +/// MFS_ZERO Only write block 0. +/// +/// @return FAIL If failure. Possible causes: +/// - No file (nothing to do). +/// - Write error (probably full disk). +/// OK Otherwise. int mf_sync(memfile_T *mfp, int flags) { int status; @@ -454,21 +428,18 @@ int mf_sync(memfile_T *mfp, int flags) #endif int got_int_save = got_int; - if (mfp->mf_fd < 0) { /* there is no file, nothing to do */ + if (mfp->mf_fd < 0) { // there is no file, nothing to do mfp->mf_dirty = FALSE; return FAIL; } - /* Only a CTRL-C while writing will break us here, not one typed - * previously. */ + // Only a CTRL-C while writing will break us here, not one typed previously. got_int = FALSE; - /* - * sync from last to first (may reduce the probability of an inconsistent - * file) If a write fails, it is very likely caused by a full filesystem. - * Then we only try to write blocks within the existing file. If that also - * fails then we give up. - */ + // Sync from last to first (may reduce the probability of an inconsistent + // file). If a write fails, it is very likely caused by a full filesystem. + // Then we only try to write blocks within the existing file. If that also + // fails then we give up. status = OK; for (hp = mfp->mf_used_last; hp != NULL; hp = hp->bh_prev) if (((flags & MFS_ALL) || hp->bh_bnum >= 0) @@ -478,12 +449,11 @@ int mf_sync(memfile_T *mfp, int flags) if ((flags & MFS_ZERO) && hp->bh_bnum != 0) continue; if (mf_write(mfp, hp) == FAIL) { - if (status == FAIL) /* double error: quit syncing */ + if (status == FAIL) // double error: quit syncing break; status = FAIL; } - if (flags & MFS_STOP) { - /* Stop when char available now. */ + if (flags & MFS_STOP) { // Stop when char available now. if (ui_char_avail()) break; } else @@ -492,10 +462,8 @@ int mf_sync(memfile_T *mfp, int flags) break; } - /* - * If the whole list is flushed, the memfile is not dirty anymore. - * In case of an error this flag is also set, to avoid trying all the time. - */ + // If the whole list is flushed, the memfile is not dirty anymore. + // In case of an error, dirty flag is also set, to avoid trying all the time. if (hp == NULL || status == FAIL) mfp->mf_dirty = FALSE; @@ -507,8 +475,8 @@ int mf_sync(memfile_T *mfp, int flags) status = FAIL; } else # endif - /* OpenNT is strictly POSIX (Benzinger) */ - /* Tandem/Himalaya NSK-OSS doesn't have sync() */ + // OpenNT is strictly POSIX (Benzinger). + // Tandem/Himalaya NSK-OSS doesn't have sync() # if defined(__OPENNT) || defined(__TANDEM) fflush(NULL); # else @@ -516,10 +484,8 @@ int mf_sync(memfile_T *mfp, int flags) # endif #endif # ifdef SYNC_DUP_CLOSE - /* - * Win32 is a bit more work: Duplicate the file handle and close it. - * This should flush the file to disk. - */ + // Win32 is a bit more work: Duplicate the file handle and close it. + // This should flush the file to disk. if ((fd = dup(mfp->mf_fd)) >= 0) close(fd); # endif @@ -530,11 +496,8 @@ int mf_sync(memfile_T *mfp, int flags) return status; } -/* - * For all blocks in memory file *mfp that have a positive block number set - * the dirty flag. These are blocks that need to be written to a newly - * created swapfile. - */ +/// Set dirty flag for all blocks in memory file with a positive block number. +/// These are blocks that need to be written to a newly created swapfile. void mf_set_dirty(memfile_T *mfp) { bhdr_T *hp; @@ -545,39 +508,31 @@ void mf_set_dirty(memfile_T *mfp) mfp->mf_dirty = TRUE; } -/* - * insert block *hp in front of hashlist of memfile *mfp - */ +/// Insert block in front of memfile's hash list. static void mf_ins_hash(memfile_T *mfp, bhdr_T *hp) { mf_hash_add_item(&mfp->mf_hash, (mf_hashitem_T *)hp); } -/* - * remove block *hp from hashlist of memfile list *mfp - */ +/// Remove block from memfile's hash list. static void mf_rem_hash(memfile_T *mfp, bhdr_T *hp) { mf_hash_rem_item(&mfp->mf_hash, (mf_hashitem_T *)hp); } -/* - * look in hash lists of memfile *mfp for block header with number 'nr' - */ +/// Lookup block with number "nr" in memfile's hash list. static bhdr_T *mf_find_hash(memfile_T *mfp, blocknr_T nr) { return (bhdr_T *)mf_hash_find(&mfp->mf_hash, nr); } -/* - * insert block *hp in front of used list of memfile *mfp - */ +/// Insert block at the front of memfile's used list. static void mf_ins_used(memfile_T *mfp, bhdr_T *hp) { hp->bh_next = mfp->mf_used_first; mfp->mf_used_first = hp; hp->bh_prev = NULL; - if (hp->bh_next == NULL) /* list was empty, adjust last pointer */ + if (hp->bh_next == NULL) // list was empty, adjust last pointer mfp->mf_used_last = hp; else hp->bh_next->bh_prev = hp; @@ -585,52 +540,54 @@ static void mf_ins_used(memfile_T *mfp, bhdr_T *hp) total_mem_used += hp->bh_page_count * mfp->mf_page_size; } -/* - * remove block *hp from used list of memfile *mfp - */ +/// Remove block from memfile's used list. static void mf_rem_used(memfile_T *mfp, bhdr_T *hp) { - if (hp->bh_next == NULL) /* last block in used list */ + if (hp->bh_next == NULL) // last block in used list mfp->mf_used_last = hp->bh_prev; else hp->bh_next->bh_prev = hp->bh_prev; - if (hp->bh_prev == NULL) /* first block in used list */ + + if (hp->bh_prev == NULL) // first block in used list mfp->mf_used_first = hp->bh_next; else hp->bh_prev->bh_next = hp->bh_next; + mfp->mf_used_count -= hp->bh_page_count; total_mem_used -= hp->bh_page_count * mfp->mf_page_size; } -/* - * Release the least recently used block from the used list if the number - * of used memory blocks gets to big. - * - * Return the block header to the caller, including the memory block, so - * it can be re-used. Make sure the page_count is right. - */ +/// Try to release the least recently used block from the used list if the +/// number of used memory blocks gets too big. +/// +/// @return The block header, when release needed and possible. +/// Resulting block header includes memory block, so it can be +/// reused. Page count is checked to be right. +/// NULL, when release not needed, or not possible. +/// Not needed when number of blocks less than allowed maximum and +/// total memory used below 'maxmemtot'. +/// Not possible when: +/// - Called while closing file. +/// - Tried to create swap file but couldn't. +/// - All blocks are locked. +/// - Unlocked dirty block found, but flush failed. static bhdr_T *mf_release(memfile_T *mfp, int page_count) { bhdr_T *hp; int need_release; - /* don't release while in mf_close_file() */ + // don't release while in mf_close_file() if (mf_dont_release) return NULL; - /* - * Need to release a block if the number of blocks for this memfile is - * higher than the maximum or total memory used is over 'maxmemtot' - */ + /// Need to release a block if the number of blocks for this memfile is + /// higher than the maximum one or total memory used is over 'maxmemtot'. need_release = ((mfp->mf_used_count >= mfp->mf_used_count_max) || (total_mem_used >> 10) >= (long_u)p_mmt); - /* - * Try to create a swap file if the amount of memory used is getting too - * high. - */ + /// Try to create swap file if the amount of memory used is getting too high. if (mfp->mf_fd < 0 && need_release && p_uc) { - /* find for which buffer this memfile is */ + // find for which buffer this memfile is buf_T *buf = NULL; FOR_ALL_BUFFERS(bp) { if (bp->b_ml.ml_mfp == mfp) { @@ -643,37 +600,30 @@ static bhdr_T *mf_release(memfile_T *mfp, int page_count) } } - /* - * don't release a block if - * there is no file for this memfile - * or - * the number of blocks for this memfile is lower than the maximum - * and - * total memory used is not up to 'maxmemtot' - */ + /// Don't release a block if: + /// there is no file for this memfile + /// or + /// the number of blocks for this memfile is lower than the maximum + /// and + /// total memory used is not up to 'maxmemtot' if (mfp->mf_fd < 0 || !need_release) return NULL; for (hp = mfp->mf_used_last; hp != NULL; hp = hp->bh_prev) if (!(hp->bh_flags & BH_LOCKED)) break; - if (hp == NULL) /* not a single one that can be released */ + if (hp == NULL) // not a single one that can be released return NULL; - /* - * If the block is dirty, write it. - * If the write fails we don't free it. - */ + // If the block is dirty, write it. + // If the write fails we don't free it. if ((hp->bh_flags & BH_DIRTY) && mf_write(mfp, hp) == FAIL) return NULL; mf_rem_used(mfp, hp); mf_rem_hash(mfp, hp); - /* - * If a bhdr_T is returned, make sure that the page_count of bh_data is - * right - */ + /// Make sure page_count of bh_data is right. if (hp->bh_page_count != page_count) { free(hp->bh_data); hp->bh_data = xmalloc(mfp->mf_page_size * page_count); @@ -682,12 +632,12 @@ static bhdr_T *mf_release(memfile_T *mfp, int page_count) return hp; } -/* - * release as many blocks as possible - * Used in case of out of memory - * - * return TRUE if any memory was released - */ +/// Release as many blocks as possible. +/// +/// Used in case of out of memory +/// +/// @return TRUE If any memory was released. +/// FALSE If not. int mf_release_all(void) { memfile_T *mfp; @@ -697,11 +647,11 @@ int mf_release_all(void) FOR_ALL_BUFFERS(buf) { mfp = buf->b_ml.ml_mfp; if (mfp != NULL) { - /* If no swap file yet, may open one */ + // If no swap file yet, may open one. if (mfp->mf_fd < 0 && buf->b_may_swap) ml_open_file(buf); - /* only if there is a swapfile */ + // Flush as many blocks as possible, only if there is a swapfile. if (mfp->mf_fd >= 0) { for (hp = mfp->mf_used_last; hp != NULL; ) { if (!(hp->bh_flags & BH_LOCKED) @@ -710,7 +660,7 @@ int mf_release_all(void) mf_rem_used(mfp, hp); mf_rem_hash(mfp, hp); mf_free_bhdr(hp); - hp = mfp->mf_used_last; /* re-start, list was changed */ + hp = mfp->mf_used_last; // restart, list was changed retval = TRUE; } else hp = hp->bh_prev; @@ -721,9 +671,7 @@ int mf_release_all(void) return retval; } -/* - * Allocate a block header and a block of memory for it - */ +/// Allocate a block header and a block of memory for it. static bhdr_T *mf_alloc_bhdr(memfile_T *mfp, int page_count) { bhdr_T *hp = xmalloc(sizeof(bhdr_T)); @@ -733,28 +681,23 @@ static bhdr_T *mf_alloc_bhdr(memfile_T *mfp, int page_count) return hp; } -/* - * Free a block header and the block of memory for it - */ +/// Free a block header and its block memory. static void mf_free_bhdr(bhdr_T *hp) { free(hp->bh_data); free(hp); } -/* - * insert entry *hp in the free list - */ +/// Insert a block in the free list. static void mf_ins_free(memfile_T *mfp, bhdr_T *hp) { hp->bh_next = mfp->mf_free_first; mfp->mf_free_first = hp; } -/* - * remove the first entry from the free list and return a pointer to it - * Note: caller must check that mfp->mf_free_first is not NULL! - */ +/// Remove the first block in the free list and return it. +/// +/// Caller must check that mfp->mf_free_first is not NULL. static bhdr_T *mf_rem_free(memfile_T *mfp) { bhdr_T *hp; @@ -764,18 +707,19 @@ static bhdr_T *mf_rem_free(memfile_T *mfp) return hp; } -/* - * read a block from disk - * - * Return FAIL for failure, OK otherwise - */ +/// Read a block from disk. +/// +/// @return OK On success. +/// FAIL On failure. Could be: +/// - No file. +/// - Error reading file. static int mf_read(memfile_T *mfp, bhdr_T *hp) { off_t offset; unsigned page_size; unsigned size; - if (mfp->mf_fd < 0) /* there is no file, can't read */ + if (mfp->mf_fd < 0) // there is no file, can't read return FAIL; page_size = mfp->mf_page_size; @@ -793,40 +737,41 @@ static int mf_read(memfile_T *mfp, bhdr_T *hp) return OK; } -/* - * write a block to disk - * - * Return FAIL for failure, OK otherwise - */ +/// Write a block to disk. +/// +/// @return OK On success. +/// FAIL On failure. Could be: +/// - No file. +/// - Could not translate negative block number to positive. +/// - Seek error in swap file. +/// - Write error in swap file. static int mf_write(memfile_T *mfp, bhdr_T *hp) { - off_t offset; /* offset in the file */ - blocknr_T nr; /* block nr which is being written */ - bhdr_T *hp2; - unsigned page_size; /* number of bytes in a page */ - unsigned page_count; /* number of pages written */ - unsigned size; /* number of bytes written */ - - if (mfp->mf_fd < 0) /* there is no file, can't write */ + off_t offset; // offset in the file + blocknr_T nr; // block nr which is being written + bhdr_T *hp2; + unsigned page_size; // number of bytes in a page + unsigned page_count; // number of pages written + unsigned size; // number of bytes written + + if (mfp->mf_fd < 0) // there is no file, can't write return FAIL; - if (hp->bh_bnum < 0) /* must assign file block number */ + if (hp->bh_bnum < 0) // must assign file block number if (mf_trans_add(mfp, hp) == FAIL) return FAIL; page_size = mfp->mf_page_size; - /* - * We don't want gaps in the file. Write the blocks in front of *hp - * to extend the file. - * If block 'mf_infile_count' is not in the hash list, it has been - * freed. Fill the space in the file with data from the current block. - */ + /// We don't want gaps in the file. Write the blocks in front of *hp + /// to extend the file. + /// If block 'mf_infile_count' is not in the hash list, it has been + /// freed. Fill the space in the file with data from the current block. for (;; ) { nr = hp->bh_bnum; - if (nr > mfp->mf_infile_count) { /* beyond end of file */ + if (nr > mfp->mf_infile_count) { // beyond end of file nr = mfp->mf_infile_count; - hp2 = mf_find_hash(mfp, nr); /* NULL caught below */ + hp2 = mf_find_hash(mfp, nr); // NULL caught below } else hp2 = hp; @@ -835,39 +780,36 @@ static int mf_write(memfile_T *mfp, bhdr_T *hp) PERROR(_("E296: Seek error in swap file write")); return FAIL; } - if (hp2 == NULL) /* freed block, fill with dummy data */ + if (hp2 == NULL) // freed block, fill with dummy data page_count = 1; else page_count = hp2->bh_page_count; size = page_size * page_count; if (mf_write_block(mfp, hp2 == NULL ? hp : hp2, offset, size) == FAIL) { - /* - * Avoid repeating the error message, this mostly happens when the - * disk is full. We give the message again only after a successful - * write or when hitting a key. We keep on trying, in case some - * space becomes available. - */ + /// Avoid repeating the error message, this mostly happens when the + /// disk is full. We give the message again only after a successful + /// write or when hitting a key. We keep on trying, in case some + /// space becomes available. if (!did_swapwrite_msg) EMSG(_("E297: Write error in swap file")); did_swapwrite_msg = TRUE; return FAIL; } did_swapwrite_msg = FALSE; - if (hp2 != NULL) /* written a non-dummy block */ + if (hp2 != NULL) // written a non-dummy block hp2->bh_flags &= ~BH_DIRTY; - /* appended to the file */ - if (nr + (blocknr_T)page_count > mfp->mf_infile_count) + if (nr + (blocknr_T)page_count > mfp->mf_infile_count) // appended to file mfp->mf_infile_count = nr + page_count; - if (nr == hp->bh_bnum) /* written the desired block */ + if (nr == hp->bh_bnum) // written the desired block break; } return OK; } -/* - * Write block "hp" with data size "size" to file "mfp->mf_fd". - * Return FAIL or OK. - */ +/// Write block to memfile's file. +/// +/// @return OK On success. +/// FAIL On failure. static int mf_write_block(memfile_T *mfp, bhdr_T *hp, off_t offset, unsigned size) { char_u *data = hp->bh_data; @@ -879,35 +821,30 @@ static int mf_write_block(memfile_T *mfp, bhdr_T *hp, off_t offset, unsigned siz return result; } -/* - * Make block number for *hp positive and add it to the translation list - * - * Return FAIL for failure, OK otherwise - */ +/// Make block number positive and add it to the translation list. +/// +/// @return OK On success. +/// FAIL On failure. static int mf_trans_add(memfile_T *mfp, bhdr_T *hp) { bhdr_T *freep; blocknr_T new_bnum; int page_count; - if (hp->bh_bnum >= 0) /* it's already positive */ + if (hp->bh_bnum >= 0) // it's already positive return OK; NR_TRANS *np = xmalloc(sizeof(NR_TRANS)); - /* - * Get a new number for the block. - * If the first item in the free list has sufficient pages, use its number - * Otherwise use mf_blocknr_max. - */ + // Get a new number for the block. + // If the first item in the free list has sufficient pages, use its number. + // Otherwise use mf_blocknr_max. freep = mfp->mf_free_first; page_count = hp->bh_page_count; if (freep != NULL && freep->bh_page_count >= page_count) { new_bnum = freep->bh_bnum; - /* - * If the page count of the free block was larger, reduce it. - * If the page count matches, remove the block from the free list - */ + // If the page count of the free block was larger, reduce it. + // If the page count matches, remove the block from the free list. if (freep->bh_page_count > page_count) { freep->bh_bnum += page_count; freep->bh_page_count -= page_count; @@ -920,24 +857,23 @@ static int mf_trans_add(memfile_T *mfp, bhdr_T *hp) mfp->mf_blocknr_max += page_count; } - np->nt_old_bnum = hp->bh_bnum; /* adjust number */ + np->nt_old_bnum = hp->bh_bnum; // adjust number np->nt_new_bnum = new_bnum; - mf_rem_hash(mfp, hp); /* remove from old hash list */ + mf_rem_hash(mfp, hp); // remove from old hash list hp->bh_bnum = new_bnum; - mf_ins_hash(mfp, hp); /* insert in new hash list */ + mf_ins_hash(mfp, hp); // insert in new hash list - /* Insert "np" into "mf_trans" hashtable with key "np->nt_old_bnum" */ + // Insert "np" into "mf_trans" hashtable with key "np->nt_old_bnum". mf_hash_add_item(&mfp->mf_trans, (mf_hashitem_T *)np); return OK; } -/* - * Lookup a translation from the trans lists and delete the entry - * - * Return the positive new number when found, the old number when not found - */ +/// Lookup translation from trans list and delete the entry. +/// +/// @return The positive new number When found. +/// The old number When not found. blocknr_T mf_trans_del(memfile_T *mfp, blocknr_T old_nr) { NR_TRANS *np; @@ -945,13 +881,13 @@ blocknr_T mf_trans_del(memfile_T *mfp, blocknr_T old_nr) np = (NR_TRANS *)mf_hash_find(&mfp->mf_trans, old_nr); - if (np == NULL) /* not found */ + if (np == NULL) // not found return old_nr; mfp->mf_neg_count--; new_bnum = np->nt_new_bnum; - /* remove entry from the trans list */ + // remove entry from the trans list mf_hash_rem_item(&mfp->mf_trans, (mf_hashitem_T *)np); free(np); @@ -959,20 +895,19 @@ blocknr_T mf_trans_del(memfile_T *mfp, blocknr_T old_nr) return new_bnum; } -/* - * Set mfp->mf_ffname according to mfp->mf_fname and some other things. - * Only called when creating or renaming the swapfile. Either way it's a new - * name so we must work out the full path name. - */ +/// Set full file name of memfile's swapfile, out of simple file name and some +/// other considerations. +/// +/// Only called when creating or renaming the swapfile. Either way it's a new +/// name so we must work out the full path name. void mf_set_ffname(memfile_T *mfp) { mfp->mf_ffname = FullName_save(mfp->mf_fname, FALSE); } -/* - * Make the name of the file used for the memfile a full path. - * Used before doing a :cd - */ +/// Make name of memfile's swapfile a full path. +/// +/// Used before doing a :cd void mf_fullname(memfile_T *mfp) { if (mfp != NULL && mfp->mf_fname != NULL && mfp->mf_ffname != NULL) { @@ -982,19 +917,17 @@ void mf_fullname(memfile_T *mfp) } } -/* - * return TRUE if there are any translations pending for 'mfp' - */ +/// Return TRUE if there are any translations pending for memfile. int mf_need_trans(memfile_T *mfp) { return mfp->mf_fname != NULL && mfp->mf_neg_count > 0; } -/* - * Open a swap file for a memfile. - * The "fname" must be in allocated memory, and is consumed (also when an - * error occurs). - */ +/// Open memfile's swapfile. +/// +/// "fname" must be in allocated memory, and is consumed (also when error). +/// +/// @param flags Flags for open(). static void mf_do_open ( memfile_T *mfp, @@ -1002,35 +935,24 @@ mf_do_open ( int flags /* flags for open() */ ) { + // fname cannot be NameBuff, because it must have been allocated. mfp->mf_fname = fname; - - /* - * Get the full path name before the open, because this is - * not possible after the open on the Amiga. - * fname cannot be NameBuff, because it must have been allocated. - */ mf_set_ffname(mfp); - /* - * Extra security check: When creating a swap file it really shouldn't - * exist yet. If there is a symbolic link, this is most likely an attack. - */ + /// Extra security check: When creating a swap file it really shouldn't + /// exist yet. If there is a symbolic link, this is most likely an attack. FileInfo file_info; if ((flags & O_CREAT) && os_fileinfo_link((char *)mfp->mf_fname, &file_info)) { mfp->mf_fd = -1; EMSG(_("E300: Swap file already exists (symlink attack?)")); } else { - /* - * try to open the file - */ + // try to open the file flags |= O_NOFOLLOW; mfp->mf_fd = mch_open_rw((char *)mfp->mf_fname, flags); } - /* - * If the file cannot be opened, use memory only - */ + // If the file cannot be opened, use memory only if (mfp->mf_fd < 0) { free(mfp->mf_fname); free(mfp->mf_ffname); @@ -1045,25 +967,21 @@ mf_do_open ( #ifdef HAVE_SELINUX mch_copy_sec(fname, mfp->mf_fname); #endif - mch_hide(mfp->mf_fname); /* try setting the 'hidden' flag */ + mch_hide(mfp->mf_fname); // try setting the 'hidden' flag } } -/* - * Implementation of mf_hashtab_T follows. - */ +// +// Implementation of mf_hashtab_T. +// -/* - * The number of buckets in the hashtable is increased by a factor of - * MHT_GROWTH_FACTOR when the average number of items per bucket - * exceeds 2 ^ MHT_LOG_LOAD_FACTOR. - */ +/// The number of buckets in the hashtable is increased by a factor of +/// MHT_GROWTH_FACTOR when the average number of items per bucket +/// exceeds 2 ^ MHT_LOG_LOAD_FACTOR. #define MHT_LOG_LOAD_FACTOR 6 -#define MHT_GROWTH_FACTOR 2 /* must be a power of two */ +#define MHT_GROWTH_FACTOR 2 // must be a power of two -/* - * Initialize an empty hash table. - */ +/// Initialize an empty hash table. static void mf_hash_init(mf_hashtab_T *mht) { memset(mht, 0, sizeof(mf_hashtab_T)); @@ -1071,19 +989,15 @@ static void mf_hash_init(mf_hashtab_T *mht) mht->mht_mask = MHT_INIT_SIZE - 1; } -/* - * Free the array of a hash table. Does not free the items it contains! - * The hash table must not be used again without another mf_hash_init() call. - */ +/// Free the array of a hash table. Does not free the items it contains! +/// The hash table must not be used again without another mf_hash_init() call. static void mf_hash_free(mf_hashtab_T *mht) { if (mht->mht_buckets != mht->mht_small_buckets) free(mht->mht_buckets); } -/* - * Free the array of a hash table and all the items it contains. - */ +/// Free the array of a hash table and all the items it contains. static void mf_hash_free_all(mf_hashtab_T *mht) { long_u idx; @@ -1099,10 +1013,9 @@ static void mf_hash_free_all(mf_hashtab_T *mht) mf_hash_free(mht); } -/* - * Find "key" in hashtable "mht". - * Returns a pointer to a mf_hashitem_T or NULL if the item was not found. - */ +/// Find by key. +/// +/// @return A pointer to a mf_hashitem_T or NULL if the item was not found. static mf_hashitem_T *mf_hash_find(mf_hashtab_T *mht, blocknr_T key) { mf_hashitem_T *mhi; @@ -1114,10 +1027,7 @@ static mf_hashitem_T *mf_hash_find(mf_hashtab_T *mht, blocknr_T key) return mhi; } -/* - * Add item "mhi" to hashtable "mht". - * "mhi" must not be NULL. - */ +/// Add item to hashtable. Item must not be NULL. static void mf_hash_add_item(mf_hashtab_T *mht, mf_hashitem_T *mhi) { long_u idx; @@ -1131,20 +1041,15 @@ static void mf_hash_add_item(mf_hashtab_T *mht, mf_hashitem_T *mhi) mht->mht_count++; - /* - * Grow hashtable when we have more thank 2^MHT_LOG_LOAD_FACTOR - * items per bucket on average - */ + /// Grow hashtable when we have more thank 2^MHT_LOG_LOAD_FACTOR + /// items per bucket on average. if (mht->mht_fixed == 0 && (mht->mht_count >> MHT_LOG_LOAD_FACTOR) > mht->mht_mask) { mf_hash_grow(mht); } } -/* - * Remove item "mhi" from hashtable "mht". - * "mhi" must not be NULL and must have been inserted into "mht". - */ +/// Remove item from hashtable. Item must be non NULL and within hashtable. static void mf_hash_rem_item(mf_hashtab_T *mht, mf_hashitem_T *mhi) { if (mhi->mhi_prev == NULL) @@ -1157,14 +1062,12 @@ static void mf_hash_rem_item(mf_hashtab_T *mht, mf_hashitem_T *mhi) mht->mht_count--; - /* We could shrink the table here, but it typically takes little memory, - * so why bother? */ + // We could shrink the table here, but it typically takes little memory, + // so why bother? } -/* - * Increase number of buckets in the hashtable by MHT_GROWTH_FACTOR and - * rehash items. - */ +/// Increase number of buckets in the hashtable by MHT_GROWTH_FACTOR and +/// rehash items. static void mf_hash_grow(mf_hashtab_T *mht) { long_u i, j; @@ -1182,16 +1085,14 @@ static void mf_hash_grow(mf_hashtab_T *mht) shift++; for (i = 0; i <= mht->mht_mask; i++) { - /* - * Traverse the items in the i-th original bucket and move them into - * MHT_GROWTH_FACTOR new buckets, preserving their relative order - * within each new bucket. Preserving the order is important because - * mf_get() tries to keep most recently used items at the front of - * each bucket. - * - * Here we strongly rely on the fact the hashes are computed modulo - * a power of two. - */ + /// Traverse the items in the i-th original bucket and move them into + /// MHT_GROWTH_FACTOR new buckets, preserving their relative order + /// within each new bucket. Preserving the order is important because + /// mf_get() tries to keep most recently used items at the front of + /// each bucket. + /// + /// Here we strongly rely on the fact that hashes are computed modulo + /// a power of two. memset(tails, 0, sizeof(tails)); diff --git a/src/nvim/memfile.h b/src/nvim/memfile.h index 3e71853326..085fa22f12 100644 --- a/src/nvim/memfile.h +++ b/src/nvim/memfile.h @@ -4,11 +4,11 @@ #include "nvim/buffer_defs.h" #include "nvim/memfile_defs.h" -/* flags for mf_sync() */ -#define MFS_ALL 1 /* also sync blocks with negative numbers */ -#define MFS_STOP 2 /* stop syncing when a character is available */ -#define MFS_FLUSH 4 /* flushed file to disk */ -#define MFS_ZERO 8 /* only write block 0 */ +/// flags for mf_sync() +#define MFS_ALL 1 /// also sync blocks with negative numbers +#define MFS_STOP 2 /// stop syncing when a character is available +#define MFS_FLUSH 4 /// flushed file to disk +#define MFS_ZERO 8 /// only write block 0 #ifdef INCLUDE_GENERATED_DECLARATIONS # include "memfile.h.generated.h" diff --git a/src/nvim/memfile_defs.h b/src/nvim/memfile_defs.h index 2e6e914b57..5dc17a751a 100644 --- a/src/nvim/memfile_defs.h +++ b/src/nvim/memfile_defs.h @@ -4,15 +4,21 @@ #include "nvim/types.h" typedef struct block_hdr bhdr_T; -typedef long blocknr_T; -/* - * mf_hashtab_T is a chained hashtable with blocknr_T key and arbitrary - * structures as items. This is an intrusive data structure: we require - * that items begin with mf_hashitem_T which contains the key and linked - * list pointers. List of items in each bucket is doubly-linked. - */ +/// A block number. +/// +/// Blocks numbered from 0 upwards have been assigned a place in the actual +/// file. The block number is equal to the page number in the file. The blocks +/// with negative numbers are currently in memory only. +typedef long blocknr_T; +/// A hash item. +/// +/// Items' keys are block numbers. +/// Items in the same bucket are organized into a doubly-linked list. +/// +/// Therefore, items can be arbitrary data structures beginning with pointers +/// for the list and and a block number key. typedef struct mf_hashitem_S mf_hashitem_T; struct mf_hashitem_S { @@ -21,79 +27,86 @@ struct mf_hashitem_S { blocknr_T mhi_key; }; +/// Initial size for a hashtable. #define MHT_INIT_SIZE 64 +/// A chained hashtable with block numbers as keys and arbitrary data structures +/// as items. +/// +/// This is an intrusive data structure: we require that items begin with +/// mf_hashitem_T which contains the key and linked list pointers. List of items +/// in each bucket is doubly-linked. typedef struct mf_hashtab_S { - long_u mht_mask; /* mask used for hash value (nr of items - * in array is "mht_mask" + 1) */ - long_u mht_count; /* nr of items inserted into hashtable */ - mf_hashitem_T **mht_buckets; /* points to mht_small_buckets or - *dynamically allocated array */ - mf_hashitem_T *mht_small_buckets[MHT_INIT_SIZE]; /* initial buckets */ - char mht_fixed; /* non-zero value forbids growth */ + long_u mht_mask; /// mask used to mod hash value to array index + /// (nr of items in array is 'mht_mask + 1') + long_u mht_count; /// number of items inserted + mf_hashitem_T **mht_buckets; /// points to the array of buckets (can be + /// mht_small_buckets or a newly allocated array + /// when mht_small_buckets becomes too small) + mf_hashitem_T *mht_small_buckets[MHT_INIT_SIZE]; /// initial buckets + char mht_fixed; /// non-zero value forbids growth } mf_hashtab_T; -/* - * for each (previously) used block in the memfile there is one block header. - * - * The block may be linked in the used list OR in the free list. - * The used blocks are also kept in hash lists. - * - * The used list is a doubly linked list, most recently used block first. - * The blocks in the used list have a block of memory allocated. - * mf_used_count is the number of pages in the used list. - * The hash lists are used to quickly find a block in the used list. - * The free list is a single linked list, not sorted. - * The blocks in the free list have no block of memory allocated and - * the contents of the block in the file (if any) is irrelevant. - */ - +/// A block header. +/// +/// There is a block header for each previously used block in the memfile. +/// +/// The block may be linked in the used list OR in the free list. +/// The used blocks are also kept in hash lists. +/// +/// The used list is a doubly linked list, most recently used block first. +/// The blocks in the used list have a block of memory allocated. +/// mf_used_count is the number of pages in the used list. +/// The hash lists are used to quickly find a block in the used list. +/// The free list is a single linked list, not sorted. +/// The blocks in the free list have no block of memory allocated and +/// the contents of the block in the file (if any) is irrelevant. struct block_hdr { - mf_hashitem_T bh_hashitem; /* header for hash table and key */ -#define bh_bnum bh_hashitem.mhi_key /* block number, part of bh_hashitem */ + mf_hashitem_T bh_hashitem; /// header for hash table and key +#define bh_bnum bh_hashitem.mhi_key /// block number, part of bh_hashitem - bhdr_T *bh_next; /* next block_hdr in free or used list */ - bhdr_T *bh_prev; /* previous block_hdr in used list */ - char_u *bh_data; /* pointer to memory (for used block) */ - int bh_page_count; /* number of pages in this block */ + bhdr_T *bh_next; /// next block_hdr in free or used list + bhdr_T *bh_prev; /// previous block_hdr in used list + char_u *bh_data; /// pointer to memory (for used block) + int bh_page_count; /// number of pages in this block #define BH_DIRTY 1 #define BH_LOCKED 2 - char bh_flags; /* BH_DIRTY or BH_LOCKED */ + char bh_flags; // BH_DIRTY or BH_LOCKED }; -/* - * when a block with a negative number is flushed to the file, it gets - * a positive number. Because the reference to the block is still the negative - * number, we remember the translation to the new positive number in the - * double linked trans lists. The structure is the same as the hash lists. - */ +/// A block number translation list item. +/// +/// When a block with a negative number is flushed to the file, it gets +/// a positive number. Because the reference to the block is still the negative +/// number, we remember the translation to the new positive number in the +/// double linked trans lists. The structure is the same as the hash lists. typedef struct nr_trans NR_TRANS; struct nr_trans { - mf_hashitem_T nt_hashitem; /* header for hash table and key */ -#define nt_old_bnum nt_hashitem.mhi_key /* old, negative, number */ - - blocknr_T nt_new_bnum; /* new, positive, number */ + mf_hashitem_T nt_hashitem; /// header for hash table and key +#define nt_old_bnum nt_hashitem.mhi_key /// old, negative, number + blocknr_T nt_new_bnum; /// new, positive, number }; +/// A memory file. struct memfile { - char_u *mf_fname; /* name of the file */ - char_u *mf_ffname; /* idem, full path */ - int mf_fd; /* file descriptor */ - bhdr_T *mf_free_first; /* first block_hdr in free list */ - bhdr_T *mf_used_first; /* mru block_hdr in used list */ - bhdr_T *mf_used_last; /* lru block_hdr in used list */ - unsigned mf_used_count; /* number of pages in used list */ - unsigned mf_used_count_max; /* maximum number of pages in memory */ - mf_hashtab_T mf_hash; /* hash lists */ - mf_hashtab_T mf_trans; /* trans lists */ - blocknr_T mf_blocknr_max; /* highest positive block number + 1*/ - blocknr_T mf_blocknr_min; /* lowest negative block number - 1 */ - blocknr_T mf_neg_count; /* number of negative blocks numbers */ - blocknr_T mf_infile_count; /* number of pages in the file */ - unsigned mf_page_size; /* number of bytes in a page */ - int mf_dirty; /* TRUE if there are dirty blocks */ + char_u *mf_fname; /// name of the file + char_u *mf_ffname; /// idem, full path + int mf_fd; /// file descriptor + bhdr_T *mf_free_first; /// first block_hdr in free list + bhdr_T *mf_used_first; /// mru block_hdr in used list + bhdr_T *mf_used_last; /// lru block_hdr in used list + unsigned mf_used_count; /// number of pages in used list + unsigned mf_used_count_max; /// maximum number of pages in memory + mf_hashtab_T mf_hash; /// hash lists + mf_hashtab_T mf_trans; /// trans lists + blocknr_T mf_blocknr_max; /// highest positive block number + 1 + blocknr_T mf_blocknr_min; /// lowest negative block number - 1 + blocknr_T mf_neg_count; /// number of negative blocks numbers + blocknr_T mf_infile_count; /// number of pages in the file + unsigned mf_page_size; /// number of bytes in a page + int mf_dirty; /// TRUE if there are dirty blocks }; #endif // NVIM_MEMFILE_DEFS_H |