@@ -296,35 +296,105 @@ typedef int (*IO_CACHE_CALLBACK)(struct st_io_cache*);
296296
297297typedef struct st_io_cache /* Used when cacheing files */
298298{
299+ /* pos_in_file is offset in file corresponding to the first byte of
300+ byte* buffer. end_of_file is the offset of end of file for READ_CACHE
301+ and WRITE_CACHE. For SEQ_READ_APPEND it the maximum of the actual
302+ end of file and the position represented by read_end.
303+ */
299304 my_off_t pos_in_file ,end_of_file ;
305+ /* read_pos points to current read position in the buffer
306+ read_end is the non-inclusive boundary in the buffer for the currently
307+ valid read area
308+ buffer is the read buffer
309+ not sure about request_pos except that it is used in async_io
310+ */
300311 byte * read_pos ,* read_end ,* buffer ,* request_pos ;
312+ /* write_buffer is used only in WRITE caches and in SEQ_READ_APPEND to
313+ buffer writes
314+ append_read_pos is only used in SEQ_READ_APPEND, and points to the
315+ current read position in the write buffer. Note that reads in
316+ SEQ_READ_APPEND caches can happen from both read buffer (byte* buffer),
317+ and write buffer (byte* write_buffer).
318+ write_pos points to current write position in the write buffer and
319+ write_end is the non-inclusive boundary of the valid write area
320+ */
301321 byte * write_buffer , * append_read_pos , * write_pos , * write_end ;
322+ /* current_pos and current_end are convenience variables used by
323+ my_b_tell() and other routines that need to know the current offset
324+ current_pos points to &write_pos, and current_end to &write_end in a
325+ WRITE_CACHE, and &read_pos and &read_end respectively otherwise
326+ */
302327 byte * * current_pos , * * current_end ;
303- /* The lock is for append buffer used in READ_APPEND cache */
328+ /* The lock is for append buffer used in SEQ_READ_APPEND cache */
304329#ifdef THREAD
305330 pthread_mutex_t append_buffer_lock ;
306331 /* need mutex copying from append buffer to read buffer */
307- #endif
332+ #endif
333+ /* a caller will use my_b_read() macro to read from the cache
334+ if the data is already in cache, it will be simply copied with
335+ memcpy() and internal variables will be accordinging updated with
336+ no functions invoked. However, if the data is not fully in the cache,
337+ my_b_read() will call read_function to fetch the data. read_function
338+ must never be invoked directly
339+ */
308340 int (* read_function )(struct st_io_cache * ,byte * ,uint );
341+ /* same idea as in the case of read_function, except my_b_write() needs to
342+ be replaced with my_b_append() for a SEQ_READ_APPEND cache
343+ */
309344 int (* write_function )(struct st_io_cache * ,const byte * ,uint );
345+ /* specifies the type of the cache. Depending on the type of the cache
346+ certain operations might not be available and yield unpredicatable
347+ results. Details to be documented later
348+ */
310349 enum cache_type type ;
311- /* callbacks when the actual read I/O happens */
350+ /* callbacks when the actual read I/O happens. These were added and
351+ are currently used for binary logging of LOAD DATA INFILE - when a
352+ block is read from the file, we create a block create/append event, and
353+ when IO_CACHE is closed, we create an end event. These functions could,
354+ of course be used for other things
355+ */
312356 IO_CACHE_CALLBACK pre_read ;
313357 IO_CACHE_CALLBACK post_read ;
314358 IO_CACHE_CALLBACK pre_close ;
315359 void * arg ; /* for use by pre/post_read */
316360 char * file_name ; /* if used with 'open_cached_file' */
317361 char * dir ,* prefix ;
318- File file ;
362+ File file ; /* file descriptor */
363+ /* seek_not_done is set by my_b_seek() to inform the upcoming read/write
364+ operation that a seek needs to be preformed prior to the actual I/O
365+ error is 0 if the cache operation was successful, -1 if there was a
366+ "hard" error, and the actual number of I/O-ed bytes if the read/write was
367+ partial
368+ */
319369 int seek_not_done ,error ;
370+ /* buffer_length is the size of memory allocated for buffer or write_buffer
371+ read_length is the same as buffer_length except when we use async io
372+ not sure why we need it
373+ */
320374 uint buffer_length ,read_length ;
321375 myf myflags ; /* Flags used to my_read/my_write */
322376 /*
377+ alloced_buffer is 1 if the buffer was allocated by init_io_cache() and
378+ 0 if it was supplied by the user
323379 Currently READ_NET is the only one that will use a buffer allocated
324380 somewhere else
325381 */
326382 my_bool alloced_buffer ;
383+ /* init_count is incremented every time we call init_io_cache()
384+ It is not reset in end_io_cache(). This variable
385+ was introduced for slave relay logs - RELAY_LOG_INFO stores a pointer
386+ to IO_CACHE that could in some cases refer to the IO_CACHE of the
387+ currently active relay log. The IO_CACHE then could be closed,
388+ re-opened and start pointing to a different log file. In that case,
389+ we could not know reliably if this happened without init_count
390+ one must be careful with bzero() prior to the subsequent init_io_cache()
391+ call
392+ */
393+ int init_count ;
327394#ifdef HAVE_AIOWAIT
395+ /* as inidicated by ifdef, this is for async I/O, we will have
396+ Sinisa comment this some time
397+ */
328398 uint inited ;
329399 my_off_t aio_read_pos ;
330400 my_aio_result aio_result ;
@@ -369,6 +439,8 @@ typedef int (*qsort2_cmp)(const void *, const void *, const void *);
369439
370440#define my_b_tell (info ) ((info)->pos_in_file + \
371441 (uint) (*(info)->current_pos - (info)->request_pos))
442+ #define my_b_append_tell (info ) ((info)->end_of_file + \
443+ (uint) ((info)->write_pos - (info)->write_buffer))
372444
373445#define my_b_bytes_in_cache (info ) (uint) (*(info)->current_end - \
374446 *(info)->current_pos)
0 commit comments