virStorageSource: note that capacity/allocation/physical are stale caches

These three fields are cached values that do not reflect reality unless
the caller refreshes them. 'allocation' is in addition ultra-unreliable:
any guest write into a previously unallocated part of a sparse image
invalidates it, even right after a refresh.

Document this on the struct so new callers do not trust the values.

Signed-off-by: Denis V. Lunev <den@openvz.org>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>

diff --git a/src/conf/storage_source_conf.h b/src/conf/storage_source_conf.h
index 5ddcebb282d9bd6bf0f15ee217acfab8a4e34fe5..fa71a9ef394d56e828f11a3166a88010ecaccf3c 100644 (file)
--- a/src/conf/storage_source_conf.h
+++ b/src/conf/storage_source_conf.h
@@ -326,6 +326,8 @@ struct _virStorageSource {
 
     virStoragePerms *perms;
     virStorageTimestamps *timestamps;
+
+    /* Cached, unreliable. Refresh before use. */
     unsigned long long capacity; /* in bytes, 0 if unknown */
     unsigned long long allocation; /* in bytes, 0 if unknown */
     unsigned long long physical; /* in bytes, 0 if unknown */