From b3c33d993a6360f10382080398dbebcd6d6493db Mon Sep 17 00:00:00 2001 From: Thomas Harte Date: Sat, 31 Dec 2016 15:30:48 -0500 Subject: [PATCH] Made an attempt to explain the requirements placed upon `Disk` subclasses that wish to support writing. --- Storage/Disk/Disk.hpp | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/Storage/Disk/Disk.hpp b/Storage/Disk/Disk.hpp index f574f2c28..c1d97d115 100644 --- a/Storage/Disk/Disk.hpp +++ b/Storage/Disk/Disk.hpp @@ -115,13 +115,30 @@ class Disk { */ virtual std::shared_ptr get_uncached_track_at_position(unsigned int head, unsigned int position) = 0; + /*! + Subclasses that support writing should implement @c store_updated_track_at_position to determine which bytes + have to be written from @c track, then obtain @c file_access_mutex and write new data to their file to represent + the track underneath @c head at @c position. + The base class will ensure that calls are made to @c get_uncached_track_at_position only while it holds @c file_access_mutex; + that mutex therefore provides serialisation of file access. + + This method will be called asynchronously. Subclasses are responsible for any synchronisation other than that + provided automatically via @c file_access_mutex. + */ virtual void store_updated_track_at_position(unsigned int head, unsigned int position, const std::shared_ptr &track, std::mutex &file_access_mutex); + + /*! + Subclasses that support writing should call @c flush_updates during their destructor if there is anything they + do in @c store_updated_track_at_position that would not be valid after their destructor has completed but prior + to Disk's constructor running. + */ void flush_updates(); private: - std::map> cached_tracks_; int get_id_for_track_at_position(unsigned int head, unsigned int position); + std::map> cached_tracks_; + std::mutex file_access_mutex_; std::unique_ptr update_queue_; };