1 
2 /* -*- c-basic-offset: 4 indent-tabs-mode: nil -*-  vi:set ts=8 sts=4 sw=4: */
3 
4 /*
5     Sonic Visualiser
6     An audio file viewer and annotation editor.
7     Centre for Digital Music, Queen Mary, University of London.
8     This file copyright 2006 QMUL.
9 
10     This program is free software; you can redistribute it and/or
11     modify it under the terms of the GNU General Public License as
12     published by the Free Software Foundation; either version 2 of the
13     License, or (at your option) any later version.  See the file
14     COPYING included with this distribution for more information.
15 */
16 
17 #ifndef SV_STORAGE_ADVISER_H
18 #define SV_STORAGE_ADVISER_H
19 
20 #include <cstdlib>
21 
22 #include <QString>
23 
24 /**
25  * A utility class designed to help decide whether to store cache data
26  * (for example FFT outputs) in memory or on disk in the TempDirectory.
27  * This is basically a compendium of simple rules of thumb.
28  */
29 
30 class StorageAdviser
31 {
32 public:
33     // pass to recommend() zero or more of these OR'd together
34     enum Criteria {
35         NoCriteria           = 0,
36         SpeedCritical        = 1,
37         PrecisionCritical    = 2,
38         LongRetentionLikely  = 4,
39         FrequentLookupLikely = 8
40     };
41 
42     // recommend() returns one or two of these OR'd together
43     enum Recommendation {
44         NoRecommendation   = 0,
45         UseMemory          = 1, // Disc is strongly contraindicated
46         PreferMemory       = 2, // Either would do; memory probably better
47         PreferDisc         = 4, // Either would do; disc probably better
48         UseDisc            = 8, // Probably won't fit in memory
49         ConserveSpace      = 16,// Whatever you choose, keep it compact
50         UseAsMuchAsYouLike = 32 // Take my advice and there'll be space for all
51     };
52 
53     /**
54      * Recommend where to store some data, given certain storage and
55      * recall criteria.  The minimum size is the approximate amount of
56      * data in kilobytes that will be stored if the recommendation is
57      * to ConserveSpace; the maximum size is approximately the amount
58      * that will be used if UseAsMuchAsYouLike is returned.
59      *
60      * May throw InsufficientDiscSpace exception if there appears to
61      * be nowhere the minimum amount of data can be stored.
62      */
63     static Recommendation recommend(Criteria criteria,
64                                     size_t minimumSize,
65                                     size_t maximumSize);
66 
67     enum AllocationArea {
68         MemoryAllocation,
69         DiscAllocation
70     };
71 
72     /**
73      * Specify that we are planning to use a given amount of storage
74      * (in kilobytes), but haven't allocated it yet.
75      */
76     static void notifyPlannedAllocation(AllocationArea area, size_t size);
77 
78     /**
79      * Specify that we have now allocated, or abandoned the allocation
80      * of, the given amount (in kilobytes) of a storage area that was
81      * previously notified using notifyPlannedAllocation.
82      */
83     static void notifyDoneAllocation(AllocationArea area, size_t size);
84 
85     /**
86      * Force all subsequent recommendations to use the (perhaps
87      * partial) specification given here.  If NoRecommendation given
88      * here, this will reset to the default free behaviour.
89      */
90     static void setFixedRecommendation(Recommendation recommendation);
91 
92 private:
93     static size_t m_discPlanned;
94     static size_t m_memoryPlanned;
95     static Recommendation m_baseRecommendation;
96 
97     enum StorageStatus {
98         Unknown,
99         Insufficient,
100         Marginal,
101         Sufficient
102     };
103 
104     static QString criteriaToString(int);
105     static QString recommendationToString(int);
106     static QString storageStatusToString(StorageStatus);
107 };
108 
109 #endif
110 
111