VirtualBox

Changeset 78299 in vbox for trunk/src


Ignore:
Timestamp:
Apr 25, 2019 5:11:49 PM (6 years ago)
Author:
vboxsync
Message:

FE/Qt: bugref:7127: Heavy cleanup for UIMediumEnumerator classes: Doxygen, comments.

Location:
trunk/src/VBox/Frontends/VirtualBox/src/medium
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/VBox/Frontends/VirtualBox/src/medium/UIMediumEnumerator.cpp

    r78298 r78299  
    3232
    3333
     34/** Template function to convert a list of
     35  * abstract objects to a human readable string list.
     36  * @note T should have .toString() member implemented. */
    3437template<class T> static QStringList toStringList(const QList<T> &list)
    3538{
    … …  
    4144
    4245
    43 /** UITask extension used for medium enumeration purposes. */
     46/** UITask extension used for medium-enumeration purposes.
     47  * @note Indeed property/setProperty API isn't thread-safe stuff.
     48  *       This isn't dangerous for us since setter/getter API calls
     49  *       are splitted in time by enumerator's logic, but latest Qt
     50  *       versions prohibits property/setProperty API usage from
     51  *       other than the GUI thread anyway so we will have to rework
     52  *       that stuff to be thread-safe one day at least for Qt >= 5.11. */
    4453class UITaskMediumEnumeration : public UITask
    4554{
    … …  
    4857public:
    4958
    50     /** Constructs @a medium enumeration task. */
     59    /** Constructs @a medium-enumeration task. */
    5160    UITaskMediumEnumeration(const UIMedium &medium)
    5261        : UITask(UITask::Type_MediumEnumeration)
    5362    {
    5463        /* Store medium as property: */
     64        /// @todo rework to thread-safe stuff one day
    5565        setProperty("medium", QVariant::fromValue(medium));
    5666    }
    … …  
    5868private:
    5969
    60     /** Contains medium enumeration task body. */
     70    /** Contains medium-enumeration task body. */
    6171    virtual void run() /* override */
    6272    {
    6373        /* Get medium: */
     74        /// @todo rework to thread-safe stuff one day
    6475        UIMedium guiMedium = property("medium").value<UIMedium>();
    6576        /* Enumerate it: */
    … …  
    7081};
    7182
     83
     84/*********************************************************************************************************************************
     85*   Class UIMediumEnumerator implementation.                                                                                     *
     86*********************************************************************************************************************************/
    7287
    7388UIMediumEnumerator::UIMediumEnumerator()
    … …  
    91106            this, &UIMediumEnumerator::sltHandleMachineRegistration);
    92107
    93     /* Listen for global thread-pool: */
     108    /* Prepare global thread-pool listener: */
    94109    connect(vboxGlobal().threadPool(), &UIThreadPool::sigTaskComplete,
    95110            this, &UIMediumEnumerator::sltHandleMediumEnumerationTaskComplete);
    … …  
    98113QList<QUuid> UIMediumEnumerator::mediumIDs() const
    99114{
    100     /* Return keys of current medium-map: */
     115    /* Return keys of current media map: */
    101116    return m_media.keys();
    102117}
    … …  
    104119UIMedium UIMediumEnumerator::medium(const QUuid &uMediumID) const
    105120{
    106     /* Search through current medium-map for the medium with passed ID: */
     121    /* Search through current media map
     122     * for the UIMedium with passed ID: */
    107123    if (m_media.contains(uMediumID))
    108124        return m_media.value(uMediumID);
    109     /* Return NULL medium otherwise: */
     125    /* Return NULL UIMedium otherwise: */
    110126    return UIMedium();
    111127}
    … …  
    113129void UIMediumEnumerator::createMedium(const UIMedium &guiMedium)
    114130{
    115     /* Get medium ID: */
     131    /* Get UIMedium ID: */
    116132    const QUuid uMediumID = guiMedium.id();
    117133
    118134    /* Do not create UIMedium(s) with incorrect ID: */
    119135    AssertReturnVoid(!uMediumID.isNull());
    120     /* Make sure medium doesn't exists already: */
     136    /* Make sure UIMedium doesn't exist already: */
    121137    AssertReturnVoid(!m_media.contains(uMediumID));
    122138
    123     /* Insert medium: */
     139    /* Insert UIMedium: */
    124140    m_media[uMediumID] = guiMedium;
    125141    LogRel(("GUI: UIMediumEnumerator: Medium with key={%s} created\n", uMediumID.toString().toUtf8().constData()));
    … …  
    133149    /* Do not delete UIMedium(s) with incorrect ID: */
    134150    AssertReturnVoid(!uMediumID.isNull());
    135     /* Make sure medium still exists: */
     151    /* Make sure UIMedium still exists: */
    136152    AssertReturnVoid(m_media.contains(uMediumID));
    137153
    138     /* Remove medium: */
     154    /* Remove UIMedium: */
    139155    m_media.remove(uMediumID);
    140156    LogRel(("GUI: UIMediumEnumerator: Medium with key={%s} deleted\n", uMediumID.toString().toUtf8().constData()));
    … …  
    149165    AssertReturnVoid(!m_fMediumEnumerationInProgress);
    150166
    151     /* Compose new map of all currently known media & their children.
    152      * While composing we are using data from already existing media. */
     167    /* Compose new map of currently cached media & their children.
     168     * While composing we are using data from already cached media. */
    153169    UIMediumMap media;
    154170    addNullMediumToMap(media);
    155     /* If @p mediaList is empty we start the media enumeration with all known media: */
     171    /* If @p inputMedia is empty we start the media enumeration with all
     172     * known hard disk media. Otherwise only passed inputMedia will be
     173     * enumerated. But be aware we will enumerate all the optical/floppy
     174     * media in any case to make them listed within the first run wizard
     175     * for now. But I think later we can add proper enumeration call to
     176     * the wizard instead and enumerate only inputMedia in 'else' case. */
    156177    if (inputMedia.isEmpty())
    157178    {
    … …  
    168189        addMediaToMap(inputMedia, media);
    169190    }
     191
     192    /* VBoxGlobal is cleaning up, abort immediately: */
    170193    if (VBoxGlobal::isCleaningUp())
    171         return; /* VBoxGlobal is cleaning up, abort immediately. */
     194        return;
     195
     196    /* Remember new media map: */
    172197    m_media = media;
    173198
    … …  
    177202    emit sigMediumEnumerationStarted();
    178203
    179     /* Make sure we really have more than one medium (which is Null): */
     204    /* Make sure we really have more than one UIMedium (which is NULL): */
    180205    if (m_media.size() == 1)
    181206    {
    … …  
    186211    }
    187212
    188     /* Start enumeration for UIMedium(s) with correct ID: */
     213    /* Start enumeration for media with non-NULL ID: */
    189214    foreach (const QUuid &uMediumID, m_media.keys())
    190215        if (!uMediumID.isNull())
    … …  
    197222    AssertReturnVoid(!m_fMediumEnumerationInProgress);
    198223
    199     /* Refresh all known media we have: */
     224    /* Refresh all cached media we have: */
    200225    foreach (const QUuid &uMediumID, m_media.keys())
    201226        m_media[uMediumID].refresh();
    … …  
    337362    if (uMediumID == UIMedium::nullID())
    338363    {
    339         /* Delete this medium: */
     364        /* Delete this UIMedium: */
    340365        m_media.remove(uMediumKey);
    341366        LogRel2(("GUI: UIMediumEnumerator: Medium with key={%s} closed and deleted (after enumeration)\n",
    … …  
    348373    else if (uMediumID != uMediumKey)
    349374    {
    350         /* We have to reinject enumerated medium: */
     375        /* We have to reinject enumerated UIMedium: */
    351376        m_media.remove(uMediumKey);
    352377        m_media[uMediumID] = guiMedium;
    … …  
    363388    else
    364389    {
    365         /* Just update enumerated medium: */
     390        /* Just update enumerated UIMedium: */
    366391        m_media[uMediumID] = guiMedium;
    367392        LogRel2(("GUI: UIMediumEnumerator: Medium with key={%s} updated\n",
    … …  
    394419void UIMediumEnumerator::addNullMediumToMap(UIMediumMap &media)
    395420{
    396     /* Insert NULL uimedium to the passed uimedium map.
     421    /* Insert NULL UIMedium to the passed media map.
    397422     * Get existing one from the previous map if any. */
    398423    const UIMedium guiMedium = m_media.contains(UIMedium::nullID())
    … …  
    404429void UIMediumEnumerator::addMediaToMap(const CMediumVector &inputMedia, UIMediumMap &outputMedia)
    405430{
    406     /* Insert hard-disks to the passed uimedium map.
    407      * Get existing one from the previous map if any. */
     431    /* Iterate through passed inputMedia vector: */
    408432    foreach (const CMedium &comMedium, inputMedia)
    409433    {
    … …  
    412436            break;
    413437
    414         /* Prepare uimedium on the basis of current medium: */
     438        /* Insert UIMedium to the passed media map.
     439         * Get existing one from the previous map if any.
     440         * Create on the basis of comMedium otherwise. */
    415441        const QUuid uMediumID = comMedium.GetId();
    416442        const UIMedium guiMedium = m_media.contains(uMediumID)
    417443                                 ? m_media.value(uMediumID)
    418444                                 : UIMedium(comMedium, UIMediumDefs::mediumTypeToLocal(comMedium.GetDeviceType()));
    419         /* Insert uimedium into map: */
    420445        outputMedia.insert(guiMedium.id(), guiMedium);
    421446
    422         /* Insert medium children into map too: */
     447        /* Insert comMedium children into map as well: */
    423448        addMediaToMap(comMedium.GetChildren(), outputMedia);
    424449    }
    425450}
    426451
    427 /**
    428  * Calculates last known UIMedium <i>usage</i> based on cached data.
    429  * @param uMachineID describes the machine we are calculating <i>usage</i> for.
    430  * @param previousUIMediumIDs receives UIMedium IDs used in cached data.
    431  * @param fTakeIntoAccountCurrentStateOnly defines whether we should take into accound current VM state only.
    432  */
    433452void UIMediumEnumerator::calculateCachedUsage(const QUuid &uMachineID,
    434453                                              QList<QUuid> &previousUIMediumIDs,
    435454                                              const bool fTakeIntoAccountCurrentStateOnly) const
    436455{
    437     /* For each the UIMedium ID cache have: */
     456    /* For each the cached UIMedium we have: */
    438457    foreach (const QUuid &uUIMediumID, mediumIDs())
    439458    {
    … …  
    451470}
    452471
    453 /**
    454  * Calculates new CMedium <i>usage</i> based on actual data.
    455  * @param uMachineID describes the machine we are calculating <i>usage</i> for.
    456  * @param currentCMediums receives CMedium used in actual data.
    457  * @param currentCMediumIDs receives CMedium IDs used in actual data.
    458  * @param fTakeIntoAccountCurrentStateOnly defines whether we should take into accound current VM state only.
    459  */
    460472void UIMediumEnumerator::calculateActualUsage(const QUuid &uMachineID,
    461473                                              CMediumMap &currentCMediums,
    … …  
    479491}
    480492
    481 /**
    482  * Calculates new CMedium <i>usage</i> based on actual data.
    483  * @param snapshot is reference we are calculating <i>usage</i> for.
    484  * @param currentCMediums receives CMedium used in actual data.
    485  * @param currentCMediumIDs receives CMedium IDs used in actual data.
    486  */
    487493void UIMediumEnumerator::calculateActualUsage(const CSnapshot &comSnapshot,
    488494                                              CMediumMap &currentCMediums,
    … …  
    501507}
    502508
    503 /**
    504  * Calculates new CMedium <i>usage</i> based on actual data.
    505  * @param machine is reference we are calculating <i>usage</i> for.
    506  * @param currentCMediums receives CMedium used in actual data.
    507  * @param currentCMediumIDs receives CMedium IDs used in actual data.
    508  */
    509509void UIMediumEnumerator::calculateActualUsage(const CMachine &comMachine,
    510510                                              CMediumMap &currentCMediums,
    … …  
    533533}
    534534
    535 /**
    536  * Updates cache using known changes in cached data.
    537  * @param previousUIMediumIDs reflects UIMedium IDs used in cached data.
    538  */
    539535void UIMediumEnumerator::recacheFromCachedUsage(const QList<QUuid> &previousUIMediumIDs)
    540536{
    … …  
    572568}
    573569
    574 /**
    575  * Updates cache using known changes in actual data.
    576  * @param currentCMediums reflects CMedium used in actual data.
    577  * @param currentCMediumIDs reflects CMedium IDs used in actual data.
    578  */
    579570void UIMediumEnumerator::recacheFromActualUsage(const CMediumMap &currentCMediums,
    580571                                                const QList<QUuid> &currentCMediumIDs)

  • trunk/src/VBox/Frontends/VirtualBox/src/medium/UIMediumEnumerator.h

    r78298 r78299  
    3535class UIThreadPool;
    3636
    37 /* Typedefs: */
     37/** A map of CMedium objects ordered by their IDs. */
    3838typedef QMap<QUuid, CMedium> CMediumMap;
    3939
    40 /* Medium-enumerator prototype.
    41  * Manages access to medium information using thread-pool interface. */
     40/** QObject extension operating as medium-enumeration object.
     41  * Manages access to cached UIMedium information via public API.
     42  * Updates cache on corresponding Main events using thread-pool interface. */
    4243class SHARED_LIBRARY_STUFF UIMediumEnumerator : public QIWithRetranslateUI3<QObject>
    4344{
    … …  
    4647signals:
    4748
    48     /* Notifiers: Medium-operations stuff: */
     49    /** Notifies listeners about UIMedium with @a uMediumID created. */
    4950    void sigMediumCreated(const QUuid &uMediumID);
     51    /** Notifies listeners about UIMedium with @a uMediumID deleted. */
    5052    void sigMediumDeleted(const QUuid &uMediumID);
    5153
    52     /* Notifiers: Medium-enumeration stuff: */
     54    /** Notifies listeners about consolidated medium-enumeration process has started. */
    5355    void sigMediumEnumerationStarted();
     56    /** Notifies listeners about UIMedium with @a uMediumID updated. */
    5457    void sigMediumEnumerated(const QUuid &uMediumID);
     58    /** Notifies listeners about consolidated medium-enumeration process has finished. */
    5559    void sigMediumEnumerationFinished();
    5660
    … …  
    6064    UIMediumEnumerator();
    6165
    62     /* API: Medium-access stuff: */
     66    /** Returns cached UIMedium ID list. */
    6367    QList<QUuid> mediumIDs() const;
     68    /** Returns a wrapper of cached UIMedium with specified @a uMediumID. */
    6469    UIMedium medium(const QUuid &uMediumID) const;
     70
     71    /** Creates UIMedium thus caching it internally on the basis of passed @a guiMedium information. */
    6572    void createMedium(const UIMedium &guiMedium);
     73    /** Deletes UIMedium with specified @a uMediumID thus removing it from internal cache. */
    6674    void deleteMedium(const QUuid &uMediumID);
    6775
    68     /* API: Medium-enumeration stuff: */
     76    /** Returns whether consolidated medium-enumeration process is in progress. */
    6977    bool isMediumEnumerationInProgress() const { return m_fMediumEnumerationInProgress; }
     78    /** Makes a request to enumerate specified @a inputMedia.
     79      * @note  Empty list means that full/overall medium-enumeration is requested. */
    7080    void enumerateMedia(const CMediumVector &inputMedia = CMediumVector());
     81    /** Refresh all the lightweight UIMedium information for all the cached UIMedium(s).
     82      * @note  Please note that this is a lightweight version, which doesn't perform
     83      *        heavy state/accessibility checks thus doesn't require to be performed
     84      *        by a worker COM-aware thread. */
    7185    void refreshMedia();
    7286
    … …  
    7892private slots:
    7993
    80     /** Handles machine-data-change and snapshot-change events. */
     94    /** Handles machine-data-change and snapshot-change events for a machine with specified @a uMachineID. */
    8195    void sltHandleMachineUpdate(const QUuid &uMachineID);
    82     /** Handles machine-[un]registration events. */
     96    /** Handles machine-[un]registration events for a machine with specified @a uMachineID.
     97      * @param  fRegistered  Specifies whether the machine was registered or unregistered otherwise. */
    8398    void sltHandleMachineRegistration(const QUuid &uMachineID, const bool fRegistered);
    84     /** Handles snapshot-deleted events. */
     99    /** Handles snapshot-deleted events for a machine with specified @a uMachineID and a snapshot with specified @a uSnapshotID. */
    85100    void sltHandleSnapshotDeleted(const QUuid &uMachineID, const QUuid &uSnapshotID);
    86101
    87     /* Handler: Medium-enumeration stuff: */
     102    /** Handles medium-enumeration @a pTask complete signal. */
    88103    void sltHandleMediumEnumerationTaskComplete(UITask *pTask);
    89104
    90105private:
    91106
    92     /* Helpers: Medium-enumeration stuff: */
     107    /** Creates medium-enumeration task for certain @a guiMedium. */
    93108    void createMediumEnumerationTask(const UIMedium &guiMedium);
     109    /** Adds NULL UIMedium to specified @a outputMedia map. */
    94110    void addNullMediumToMap(UIMediumMap &outputMedia);
     111    /** Adds @a inputMedia to specified @a outputMedia map. */
    95112    void addMediaToMap(const CMediumVector &inputMedia, UIMediumMap &outputMedia);
    96113
    97     /* Helpers: Medium re-caching stuff: */
     114    /** Updates usage for machine with specified @a uMachineID on the basis of cached data.
     115      * @param  previousUIMediumIDs               Brings UIMedium IDs used in cached data.
     116      * @param  fTakeIntoAccountCurrentStateOnly  Brings whether we should take into accound current VM state only. */
    98117    void calculateCachedUsage(const QUuid &uMachineID,
    99118                              QList<QUuid> &previousUIMediumIDs,
    100119                              const bool fTakeIntoAccountCurrentStateOnly) const;
     120    /** Updates usage for machine with specified @a uMachineID on the basis of actual data.
     121      * @param  currentCMediums                   Brings CMedium used in actual data.
     122      * @param  currentCMediumIDs                 Brings CMedium IDs used in actual data.
     123      * @param  fTakeIntoAccountCurrentStateOnly  Brings whether we should take into accound current VM state only. */
    101124    void calculateActualUsage(const QUuid &uMachineID,
    102125                              CMediumMap &currentCMediums,
    103126                              QList<QUuid> &currentCMediumIDs,
    104127                              const bool fTakeIntoAccountCurrentStateOnly) const;
     128    /** Updates usage for machine specified by its @a comSnapshot reference on the basis of actual data.
     129      * @param  currentCMediums                   Brings CMedium used in actual data.
     130      * @param  currentCMediumIDs                 Brings CMedium IDs used in actual data. */
    105131    void calculateActualUsage(const CSnapshot &comSnapshot,
    106132                              CMediumMap &currentCMediums,
    107133                              QList<QUuid> &currentCMediumIDs) const;
     134    /** Updates usage for machine specified by own @a comMachine reference on the basis of actual data.
     135      * @param  currentCMediums                   Brings CMedium used in actual data.
     136      * @param  currentCMediumIDs                 Brings CMedium IDs used in actual data. */
    108137    void calculateActualUsage(const CMachine &comMachine,
    109138                              CMediumMap &currentCMediums,
    110139                              QList<QUuid> &currentCMediumIDs) const;
     140
     141    /** Updates cache using known changes in cached data.
     142      * @param  previousUIMediumIDs               Brings UIMedium IDs used in cached data. */
    111143    void recacheFromCachedUsage(const QList<QUuid> &previousUIMediumIDs);
     144    /** Updates cache using known changes in actual data.
     145      * @param  currentCMediums                   Brings CMedium used in actual data.
     146      * @param  currentCMediumIDs                 Brings CMedium IDs used in actual data. */
    112147    void recacheFromActualUsage(const CMediumMap &currentCMediums,
    113148                                const QList<QUuid> &currentCMediumIDs);
    114149
    115     /* Variables: */
     150    /** Holds whether consolidated medium-enumeration process is in progress. */
    116151    bool  m_fMediumEnumerationInProgress;
     152
     153    /** Holds a set of current medium-enumeration tasks. */
    117154    QSet<UITask*>  m_tasks;
     155
     156    /** Holds a map of current cached (enumerated) media. */
    118157    UIMediumMap  m_media;
    119158};
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