VirtualBox

Changeset 27120 in vbox for trunk/src/VBox/Main


Ignore:
Timestamp:
Mar 5, 2010 6:03:49 PM (15 years ago)
Author:
vboxsync
Message:

Main/MediumLock: new classes intended to manage locks for media lists and maps of such media lists. Intended to centralize locking, and separate it from the manipulation logic which is needed for merging etc.

File:
1 copied

Legend:

Unmodified
Added
Removed

  • trunk/src/VBox/Main/include/MediumLock.h

    r25892 r27120  
    33/** @file
    44 *
    5  * VirtualBox COM global declarations
     5 * VirtualBox medium object lock collections
    66 */
    77
    88/*
    9  * Copyright (C) 2008 Sun Microsystems, Inc.
     9 * Copyright (C) 2010 Sun Microsystems, Inc.
    1010 *
    1111 * This file is part of VirtualBox Open Source Edition (OSE), as
    … …  
    2222 */
    2323
    24 #ifndef ____H_GLOBAL
    25 #define ____H_GLOBAL
    26 
    27 /* generated header */
    28 #include "SchemaDefs.h"
     24#ifndef ____H_MEDIUMLOCK
     25#define ____H_MEDIUMLOCK
    2926
    3027/* interface definitions */
    3128#include "VBox/com/VirtualBox.h"
    3229
    33 #include <VBox/ostypes.h>
    34 
    3530#include <iprt/types.h>
    3631
    37 #define VBOXOSHINT_NONE                 0
    38 #define VBOXOSHINT_64BIT                RT_BIT(0)
    39 #define VBOXOSHINT_HWVIRTEX             RT_BIT(1)
    40 #define VBOXOSHINT_IOAPIC               RT_BIT(2)
     32/**
     33 * Single entry for medium lock lists. Has a medium object reference,
     34 * information about what kind of lock should be taken, and if it is
     35 * locked right now.
     36 */
     37class MediumLock
     38{
     39public:
     40    /**
     41     * Default medium lock constructor.
     42     */
     43    MediumLock();
     44
     45    /**
     46     * Default medium lock destructor.
     47     */
     48    ~MediumLock();
     49
     50    /**
     51     * Create a new medium lock description
     52     *
     53     * @param aMedium       Reference to medium object
     54     * @param aLockWrite    @c true means a write lock should be taken
     55     */
     56    MediumLock(ComObjPtr<Medium> aMedium, bool aLockWrite);
     57
     58    /**
     59     * Acquire a medium lock.
     60     */
     61    int Lock();
     62
     63    /**
     64     * Release a medium lock.
     65     */
     66    int Unlock();
     67
     68private:
     69    ComObjPtr<Medium> mMedium;
     70    bool mLockWrite;
     71};
     72
    4173
    4274/**
    43  * Contains global static definitions that can be referenced by all COM classes
    44  * regardless of the apartment.
     75 * Medium lock list. Meant for storing the ordered locking information
     76 * for a single medium chain.
    4577 */
    46 class Global
     78class MediumLockList
    4779{
    4880public:
    4981
    50     /** Represents OS Type <-> string mappings. */
    51     struct OSType
    52     {
    53         const char                 *familyId;          /* utf-8 */
    54         const char                 *familyDescription; /* utf-8 */
    55         const char                 *id;          /* utf-8 */
    56         const char                 *description; /* utf-8 */
    57         const VBOXOSTYPE            osType;
    58         const uint32_t              osHint;
    59         const uint32_t              recommendedRAM;
    60         const uint32_t              recommendedVRAM;
    61         const uint32_t              recommendedHDD;
    62         const NetworkAdapterType_T  networkAdapterType;
    63         const uint32_t              numSerialEnabled;
    64     };
    65 
    66     static const OSType sOSTypes[SchemaDefs::OSTypeId_COUNT];
    67 
    68     static const char *OSTypeId(VBOXOSTYPE aOSType);
     82    /**
     83     * Default medium lock list constructor.
     84     */
     85    MediumLockList();
    6986
    7087    /**
    71      * Returns @c true if the given machine state is an online state. This is a
    72      * recommended way to detect if the VM is online (being executed in a
    73      * dedicated process) or not. Note that some online states are also
    74      * transitional states (see #IsTransitional()).
    75      *
    76      * @remarks Saving may actually be an offline state according to the
    77      *          documentation (offline snapshot).
     88     * Default medium lock list destructor.
    7889     */
    79     static bool IsOnline(MachineState_T aState)
    80     {
    81 #if 0
    82         return aState >= MachineState_FirstOnline &&
    83                aState <= MachineState_LastOnline;
    84 #else
    85         switch (aState)
    86         {
    87             case MachineState_Running:
    88             case MachineState_Paused:
    89             case MachineState_Teleporting:
    90             case MachineState_LiveSnapshotting:
    91             case MachineState_Stuck:
    92             case MachineState_Starting:
    93             case MachineState_Stopping:
    94             case MachineState_Saving:
    95             case MachineState_Restoring:
    96             case MachineState_TeleportingPausedVM:
    97             case MachineState_TeleportingIn:
    98                 return true;
    99             default:
    100                 return false;
    101         }
    102 #endif
    103     }
     90    ~MediumLockList();
    10491
    10592    /**
    106      * Returns @c true if the given machine state is a transient state. This is
    107      * a recommended way to detect if the VM is performing some potentially
    108      * lengthy operation (such as starting, stopping, saving, discarding
    109      * snapshot, etc.). Note some (but not all) transitional states are also
    110      * online states (see #IsOnline()).
     93     * Add a new medium lock declaration to the end of the list.
     94     *
     95     * @note May be only used in unlocked state.
     96     *
     97     * @return VBox status code.
     98     * @param aMedium       Reference to medium object
     99     * @param aLockWrite    @c true means a write lock should be taken
    111100     */
    112     static bool IsTransient(MachineState_T aState)
    113     {
    114 #if 0
    115         return aState >= MachineState_FirstTransient &&
    116                aState <= MachineState_LastTransient;
    117 #else
    118         switch (aState)
    119         {
    120             case MachineState_Teleporting:
    121             case MachineState_LiveSnapshotting:
    122             case MachineState_Starting:
    123             case MachineState_Stopping:
    124             case MachineState_Saving:
    125             case MachineState_Restoring:
    126             case MachineState_TeleportingPausedVM:
    127             case MachineState_TeleportingIn:
    128             case MachineState_RestoringSnapshot:
    129             case MachineState_DeletingSnapshot:
    130             case MachineState_SettingUp:
    131                 return true;
    132             default:
    133                 return false;
    134         }
    135 #endif
    136     }
     101    int Append(ComObjPtr<Medium> aMedium, bool aLockWrite);
    137102
    138103    /**
    139      * Shortcut to <tt>IsOnline(aState) || IsTransient(aState)</tt>. When it returns
    140      * @false, the VM is turned off (no VM process) and not busy with
    141      * another exclusive operation.
     104     * Add a new medium lock declaration to the beginning of the list.
     105     *
     106     * @note May be only used in unlocked state.
     107     *
     108     * @return VBox status code.
     109     * @param aMedium       Reference to medium object
     110     * @param aLockWrite    @c true means a write lock should be taken
    142111     */
    143     static bool IsOnlineOrTransient(MachineState_T aState)
    144     {
    145         return IsOnline(aState) || IsTransient(aState);
    146     }
     112    int Prepend(ComObjPtr<Medium> aMedium, bool aLockWrite);
    147113
    148114    /**
    149      * Stringify a machine state.
     115     * Update a medium lock declaration.
    150116     *
    151      * @returns Pointer to a read only string.
    152      * @param   aState      Valid machine state.
     117     * @note May be only used in unlocked state.
     118     *
     119     * @return VBox status code.
     120     * @param aMedium       Reference to medium object
     121     * @param aLockWrite    @c true means a write lock should be taken
    153122     */
    154     static const char *stringifyMachineState(MachineState_T aState);
     123    int Update(ComObjPtr<Medium> aMedium, bool aLockWrite);
    155124
    156125    /**
    157      * Stringify a session state.
     126     * Remove a medium lock declaration.
    158127     *
    159      * @returns Pointer to a read only string.
    160      * @param   aState      Valid session state.
     128     * @note May be only used in unlocked state.
     129     *
     130     * @return VBox status code.
     131     * @param aMedium       Reference to medium object
    161132     */
    162     static const char *stringifySessionState(SessionState_T aState);
     133    int Remove(ComObjPtr<Medium> aMedium);
    163134
    164135    /**
    165      * Stringify a device type.
    166      *
    167      * @returns Pointer to a read only string.
    168      * @param   aType       The device type.
     136     * Acquire all medium locks "atomically", i.e. all or nothing.
    169137     */
    170     static const char *stringifyDeviceType(DeviceType_T aType);
     138    int Lock();
    171139
    172140    /**
    173      * Try convert a COM status code to a VirtualBox status code (VBox/err.h).
    174      *
    175      * @returns VBox status code.
    176      * @param   aComStatus      COM status code.
     141     * Release all medium locks.
    177142     */
    178     static int vboxStatusCodeFromCOM(HRESULT aComStatus);
     143    int Unlock();
     144
     145private:
     146    std::list<MediumLock> mMediumLocks;
     147    bool mIsLocked;
     148}
     149
     150/**
     151 * Medium lock list map. Meant for storing a collection of lock lists.
     152 * The usual use case is creating such a map when locking all medium chains
     153 * belonging to one VM, however that's not the limit. Be creative.
     154 */
     155class MediumLockListMap
     156{
     157public:
    179158
    180159    /**
    181      * Try convert a VirtualBox status code (VBox/err.h) to a COM status code.
    182      *
    183      * This is mainly inteded for dealing with vboxStatusCodeFromCOM() return
    184      * values.  If used on anything else, it won't be able to cope with most of the
    185      * input!
    186      *
    187      * @returns COM status code.
    188      * @param   aVBoxStatus      VBox status code.
     160     * Default medium lock list map constructor.
    189161     */
    190     static HRESULT vboxStatusCodeToCOM(int aVBoxStatus);
    191 };
     162    MediumLockListMap();
    192163
    193 #endif /* !____H_GLOBAL */
     164    /**
     165     * Default medium lock list destructor.
     166     */
     167    ~MediumLockListMap();
     168
     169private:
     170    std::map<ComObjPtr<Medium>, MediumLockList *> mMediumLocks;
     171}
     172
     173#endif /* !____H_MEDIUMLOCK */
    194174/* vi: set tabstop=4 shiftwidth=4 expandtab: */
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