VirtualBox

Changeset 22310 in vbox for trunk/src/VBox/VMM


Ignore:
Timestamp:
Aug 17, 2009 10:11:17 PM (16 years ago)
Author:
vboxsync
svn:sync-xref-src-repo-rev:
51184
Message:

PDMAsyncCompletion: Documentation for the cache

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/VBox/VMM/PDMAsyncCompletionFileCache.cpp

    r22309 r22310  
    2020 * additional information or have any questions.
    2121 */
     22
     23/** @page pg_pdm_async_completion_cache     PDM Async Completion Cache - The file I/O cache
     24 * This component implements an I/O cache for file endpoints based on the ARC algorithm.
     25 * http://en.wikipedia.org/wiki/Adaptive_Replacement_Cache
     26 *
     27 * The algorithm uses for LRU (Least frequently used) lists to store data in the cache.
     28 * Two of them contain data where one stores entries which were accessed recently and one
     29 * which is used for frequently accessed data.
     30 * The other two lists are called ghost lists and store information about the accessed range
     31 * but do not contain data. They are used to track data access. If these entries are accessed
     32 * they will push the data to a higher position in the cache preventing it from getting removed
     33 * quickly again.
     34 *
     35 * The algorithm needs to be modified to meet our requirements. Like the implementation
     36 * for the ZFS filesystem we need to handle pages with a variable size. It would
     37 * be possible to use a fixed size but would increase the computational
     38 * and memory overhead.
     39 * Because we do I/O asynchronously we also need to mark entries which are currently accessed
     40 * as non evictable to prevent removal of the entry while the data is being accessed.
     41 */
     42
     43/*******************************************************************************
     44*   Header Files                                                               *
     45*******************************************************************************/
    2246#define LOG_GROUP LOG_GROUP_PDM_ASYNC_COMPLETION
    2347#include <iprt/types.h>
    … …  
    2852#include "PDMAsyncCompletionFileInternal.h"
    2953
     54/*******************************************************************************
     55*   Internal Functions                                                         *
     56*******************************************************************************/
    3057static void pdmacFileCacheTaskCompleted(PPDMACTASKFILE pTask, void *pvUser);
    3158
     59/**
     60 * Checks consistency of a LRU list.
     61 *
     62 * @returns nothing
     63 * @param    pList         The LRU list to check.
     64 * @param    pNotInList    Element which is not allowed to occur in the list.
     65 */
    3266static void pdmacFileCacheCheckList(PPDMACFILELRULIST pList, PPDMACFILECACHEENTRY pNotInList)
    3367{
    … …  
    5892}
    5993
     94/**
     95 * Unlinks a cache entry from the LRU list it is assigned to.
     96 *
     97 * @returns nothing.
     98 * @param   pEntry    The entry to unlink.
     99 */
    60100static void pdmacFileCacheEntryRemoveFromList(PPDMACFILECACHEENTRY pEntry)
    61101{
    … …  
    101141}
    102142
     143/**
     144 * Adds a cache entry to the given LRU list unlinking it from the currently
     145 * assigned list if needed.
     146 *
     147 * @returns nothing.
     148 * @param    pList    List to the add entry to.
     149 * @param    pEntry   Entry to add.
     150 */
    103151static void pdmacFileCacheEntryAddToList(PPDMACFILELRULIST pList, PPDMACFILECACHEENTRY pEntry)
    104152{
    … …  
    150198}
    151199
     200/**
     201 * Tries to remove the given amount of bytes from a given list in the cache
     202 * moving the entries to one of the given ghosts lists
     203 *
     204 * @returns Amount of data which could be freed.
     205 * @param    pCache           Pointer to the global cache data.
     206 * @param    cbData           The amount of the data to free.
     207 * @param    pListSrc         The source list to evict data from.
     208 * @param    pGhostListSrc    The ghost list removed entries should be moved to
     209 *                            NULL if the entry should be freed.
     210 *
     211 * @notes This function may return fewer bytes than requested because entries
     212 *        may be marked as non evictable if they are used for I/O at the moment.
     213 */
    152214static size_t pdmacFileCacheEvictPagesFrom(PPDMACFILECACHEGLOBAL pCache, size_t cbData,
    153215                                           PPDMACFILELRULIST pListSrc, PPDMACFILELRULIST pGhostListDst)
    … …  
    226288}
    227289
     290/**
     291 * Tries to evict the given amount of the data from the cache.
     292 *
     293 * @returns Bytes removed.
     294 * @param    pCache    The global cache data.
     295 * @param    cbData    Number of bytes to evict.
     296 */
    228297static size_t pdmacFileCacheEvict(PPDMACFILECACHEGLOBAL pCache, size_t cbData)
    229298{
    … …  
    266335}
    267336
     337/**
     338 * Updates the cache parameters
     339 *
     340 * @returns nothing.
     341 * @param    pCache    The global cache data.
     342 * @param    pEntry    The entry usign for the update.
     343 */
    268344static void pdmacFileCacheUpdate(PPDMACFILECACHEGLOBAL pCache, PPDMACFILECACHEENTRY pEntry)
    269345{
    … …  
    293369}
    294370
     371/**
     372 * Initiates a read I/O task for the given entry.
     373 *
     374 * @returns nothing.
     375 * @param   pEntry    The entry to fetch the data to.
     376 */
    295377static void pdmacFileCacheReadFromEndpoint(PPDMACFILECACHEENTRY pEntry)
    296378{
    … …  
    315397}
    316398
     399/**
     400 * Initiates a write I/O task for the given entry.
     401 *
     402 * @returns nothing.
     403 * @param    pEntry The entry to read the data from.
     404 */
    317405static void pdmacFileCacheWriteToEndpoint(PPDMACFILECACHEENTRY pEntry)
    318406{
    … …  
    337425}
    338426
     427/**
     428 * Completion callback for I/O tasks.
     429 *
     430 * @returns nothing.
     431 * @param    pTask     The completed task.
     432 * @param    pvUser    Opaque user data.
     433 */
    339434static void pdmacFileCacheTaskCompleted(PPDMACTASKFILE pTask, void *pvUser)
    340435{
    … …  
    411506}
    412507
     508/**
     509 * Initializies the I/O cache.
     510 *
     511 * returns VBox status code.
     512 * @param    pClassFile    The global class data for file endpoints.
     513 * @param    pCfgNode      CFGM node to query configuration data from.
     514 */
    413515int pdmacFileCacheInit(PPDMASYNCCOMPLETIONEPCLASSFILE pClassFile, PCFGMNODE pCfgNode)
    414516{
    … …  
    510612}
    511613
     614/**
     615 * Destroysthe cache freeing all data.
     616 *
     617 * returns nothing.
     618 * @param    pClassFile    The global class data for file endpoints.
     619 */
    512620void pdmacFileCacheDestroy(PPDMASYNCCOMPLETIONEPCLASSFILE pClassFile)
    513621{
    … …  
    528636}
    529637
     638/**
     639 * Initializes per endpoint cache data
     640 * like the AVL tree used to access cached entries.
     641 *
     642 * @returns VBox status code.
     643 * @param    pEndpoint     The endpoint to init the cache for,
     644 * @param    pClassFile    The global class data for file endpoints.
     645 */
    530646int pdmacFileEpCacheInit(PPDMASYNCCOMPLETIONENDPOINTFILE pEndpoint, PPDMASYNCCOMPLETIONEPCLASSFILE pClassFile)
    531647{
    … …  
    538654}
    539655
     656/**
     657 * Callback for the AVL destroy routine. Frees a cache entry for this endpoint.
     658 *
     659 * @returns IPRT status code.
     660 * @param    pNode     The node to destroy.
     661 * @param    pvUser    Opaque user data.
     662 */
    540663static int pdmacFileEpCacheEntryDestroy(PAVLRFOFFNODECORE pNode, void *pvUser)
    541664{
    … …  
    555678}
    556679
     680/**
     681 * Destroys all cache ressources used by the given endpoint.
     682 *
     683 * @returns nothing.
     684 * @param    pEndpoint    The endpoint to the destroy.
     685 */
    557686void pdmacFileEpCacheDestroy(PPDMASYNCCOMPLETIONENDPOINTFILE pEndpoint)
    558687{
    … …  
    585714    while (0);
    586715
     716/**
     717 * Reads the specified data from the endpoint using the cache if possible.
     718 *
     719 * @returns VBox status code.
     720 * @param    pEndpoint     The endpoint to read from.
     721 * @param    pTask         The task structure used as identifier for this request.
     722 * @param    off           The offset to start reading from.
     723 * @param    paSegments    Pointer to the array holding the destination buffers.
     724 * @param    cSegments     Number of segments in the array.
     725 * @param    cbRead        Number of bytes to read.
     726 */
    587727int pdmacFileEpCacheRead(PPDMASYNCCOMPLETIONENDPOINTFILE pEndpoint, PPDMASYNCCOMPLETIONTASKFILE pTask,
    588728                         RTFOFF off, PCPDMDATASEG paSegments, size_t cSegments,
    … …  
    852992}
    853993
     994/**
     995 * Writes the given data to the endpoint using the cache if possible.
     996 *
     997 * @returns VBox status code.
     998 * @param    pEndpoint     The endpoint to write to.
     999 * @param    pTask         The task structure used as identifier for this request.
     1000 * @param    off           The offset to start writing to
     1001 * @param    paSegments    Pointer to the array holding the source buffers.
     1002 * @param    cSegments     Number of segments in the array.
     1003 * @param    cbWrite       Number of bytes to write.
     1004 */
    8541005int pdmacFileEpCacheWrite(PPDMASYNCCOMPLETIONENDPOINTFILE pEndpoint, PPDMASYNCCOMPLETIONTASKFILE pTask,
    8551006                          RTFOFF off, PCPDMDATASEG paSegments, size_t cSegments,
Note: See TracChangeset for help on using the changeset viewer.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette