Documentation: BufferSim

This documentation gives you an introduction to the visualization tool "BufferSim". It lists the requirements that your buffer manager must meet in order to work with the tool. Your buffer manager has to work with BufferSim!

Introduction

BufferSim is a simulation tool that simulates buffer manager operations specified by an input file. It allows the user to step through execution and visually observe the changes in the buffer pool.

Input File format

The input file is a ASCII text. (See an example here) The first line must hold an integer value specifying the number of frames in the buffer pool. Subsequent lines consist of "commands" which drive the execution. These commands can be grouped into "micro-commands", "macro-commands", and "special commands".
 

  1. Micro-commands

    2. These commands specify a change of state of the buffer pool. More specifically, they indicate every assignment to the PageID, PinCount, and Dirty variable of a given frame. These are the commands that actually modify the state of the buffer, and whose effects show up in the visualization .

    Format of micro-commands:                                                                                Meaning
    (5 spaces)PageID(TAB)<page>(TAB)<frame>              <=  Bring page <page> into frame<frame>
    (5 spaces)PinCount(TAB)(TAB)<frame>(TAB)<pin>    <=  The PinCount of frame <frame> is <pin>
    (5 spaces)Dirty(TAB)(TAB)<frame>(TAB)<dirty>         <=  The Dirty variable of frame<frame> is <dirty>

    where <###> means the actual index for that item.
     

  2. Macro-commands

    3. These commands do not directly affect the state of the buffer pool. They serve to group micro-commands by a logical buffer operation.(For example, Pin a page).

    Format:
    Macro-commands don't have leading spaces, and if a PageID follows the command name, TAB is used to separate them. An end-record is necessary to "close" each macro-command. The end-record must consist of the sting "END" followed (with no space separation) by the exact text of the initiating macro-command.

    Supported Macro-commands:                                        Meaning
    Pin page(TAB)<page>                                  <==          Pin the page <page>
    Unpin page(TAB)<page>                             <==           Unpin the page <page>
    Free page(TAB)<page>                                <==          Free the page <page>
    New page(TAB)                                           <==          New a page
    Flush page(TAB)<page>                               <==          Flush the page<page>
    Flush pages(TAB)ALL                                  <==          Flush all pages
     
     

  3. Special-commands

    4. Reading and writing page are special commands, because they differ from macro-commands (they are atomic) and from micro-commands (they don't change the state of the buffer pool).

    Format:
    (2 spaces)READ page(TAB)<page>
    (2 spaces)WRITE page(TAB)<page>

Note that macro-commands can be nested, for example, if you want to free a pinned page, you have to unpin that page first, before you can deallocate it.

 

Running BufferSim

Opening an input file

Use the Open command under the File menu, or click the toolbar button, to open an input file.
This will load the commands into the listbox on the right, and it will display the initial image of the buffer pool in the panel on the left.

Reading the display

Each rectangle in the left panel represents a frame in the buffer pool, indexed at the top left. When a value is significant (valid PageID, non-zero PinCount, set Dirty bit), it is displayed in red. Also,  a frame that is pinned is colored in gray.

Micro stepping

A Click on the 'Micro Step' button will execute one line at a time. Note that only micro commands have an effect on the buffer pool.

Macro stepping

A Click on the 'Macro Step' button will execute one whole macro-command, including all the micro-commands, special commands and lower level macro-commands within it.

Jumping

A Double click on a command that has not yet been executed will execute everything from the next scheduled command to the double-clicked command.

Synchronizing buffer updates

A Check in this box at bottom right forces the view on the left to update continuously when executing several  commands (macro commands or jumping). It animates the execution of every micro-command, but also slows down the execution significantly. Otherwise the display will always be updated at the end of a macro-step or jump.

Resetting

A Click the 'Reset' button reinitializes the buffer and resets execution to the beginning.

Requirements for BufferSim

The file written out by the buffer manager should be in the same format of an input file for the BufferSim (see details and example above).

Whenever one of the PinCount, dirty, PageID variable is changed for a given frame, a micro-command should be written out to file using the output stream declared in main.

Whenever one of the  PinPage, UnpinPage, FreePage, NewPage, FlushPage, FlushAllPages functions (i.e.  the macro commands) are called, or the disk manager reads (or writes) a page to disk (via a special-command), the corresponding macro-commands and special commands should also be written to a output file using the output stream declared in main. Since processing each macro-command  calls several micro-commands, each micro-command called must be written into the  file before the end-record of the macro-command is written. The format should be as specified above.