A fork of https://github.com/crosspoint-reader/crosspoint-reader
fix: make file system operations thread-safe (HalFile) (#1212)
## Summary
Fix https://github.com/crosspoint-reader/crosspoint-reader/issues/1137
Introducing `HalFile`, a thin wrapper around `FsFile` that uses a global
mutex to protect file operations.
To test this PR, place the code below somewhere in the code base (I
placed it in `onGoToRecentBooks`)
```cpp
static auto testTask = [](void* param) {
for (int i = 0; i < 10; i++) {
String json = Storage.readFile("/.crosspoint/settings.json");
LOG_DBG("TEST_TASK", "Read settings.json, bytes read: %u", json.length());
}
vTaskDelete(nullptr);
};
xTaskCreate(testTask, "test0", 8192, nullptr, 1, nullptr);
xTaskCreate(testTask, "test1", 8192, nullptr, 1, nullptr);
xTaskCreate(testTask, "test2", 8192, nullptr, 1, nullptr);
xTaskCreate(testTask, "test3", 8192, nullptr, 1, nullptr);
delay(1000);
```
It will reliably lead to crash on `master`, but will function correctly
with this PR.
A macro renaming trick is used to avoid changing too many downstream
code files.
---
### AI Usage
While CrossPoint doesn't have restrictions on AI tools in contributing,
please be transparent about their usage as it
helps set the right context for reviewers.
Did you use AI tools to help write this code? **PARTIALLY**, only to
help with tedious copy-paste tasks
---------
Co-authored-by: Zach Nelson <zach@zdnelson.com>
authored by
Xuan-Son Nguyen
Zach Nelson
and committed by
GitHub
6ff5fcd9
42b122b8
+181
-37
+3
-2
lib/JpegToBmpConverter/JpegToBmpConverter.h
+3
-2
lib/JpegToBmpConverter/JpegToBmpConverter.h
···
1
1
#pragma once
2
2
3
-
class FsFile;
3
+
#include <HalStorage.h>
4
+
4
5
class Print;
5
6
class ZipFile;
6
7
7
8
class JpegToBmpConverter {
8
9
static unsigned char jpegReadCallback(unsigned char* pBuf, unsigned char buf_size,
9
10
unsigned char* pBytes_actually_read, void* pCallback_data);
10
-
static bool jpegFileToBmpStreamInternal(class FsFile& jpegFile, Print& bmpOut, int targetWidth, int targetHeight,
11
+
static bool jpegFileToBmpStreamInternal(FsFile& jpegFile, Print& bmpOut, int targetWidth, int targetHeight,
11
12
bool oneBit, bool crop = true);
12
13
13
14
public:
+2
-1
lib/PngToBmpConverter/PngToBmpConverter.h
+2
-1
lib/PngToBmpConverter/PngToBmpConverter.h
+114
-22
lib/hal/HalStorage.cpp
+114
-22
lib/hal/HalStorage.cpp
···
1
+
#define HAL_STORAGE_IMPL
1
2
#include "HalStorage.h"
2
3
4
+
#include <FS.h> // need to be included before SdFat.h for compatibility with FS.h's File class
5
+
#include <Logging.h>
3
6
#include <SDCardManager.h>
7
+
8
+
#include <cassert>
4
9
5
10
#define SDCard SDCardManager::getInstance()
6
11
7
12
HalStorage HalStorage::instance;
8
13
9
-
HalStorage::HalStorage() {}
14
+
HalStorage::HalStorage() {
15
+
storageMutex = xSemaphoreCreateMutex();
16
+
assert(storageMutex != nullptr);
17
+
}
18
+
19
+
// begin() and ready() are only called from setup, no need to acquire mutex for them
10
20
11
21
bool HalStorage::begin() { return SDCard.begin(); }
12
22
13
23
bool HalStorage::ready() const { return SDCard.ready(); }
14
24
15
-
std::vector<String> HalStorage::listFiles(const char* path, int maxFiles) { return SDCard.listFiles(path, maxFiles); }
25
+
// For the rest of the methods, we acquire the mutex to ensure thread safety
16
26
17
-
String HalStorage::readFile(const char* path) { return SDCard.readFile(path); }
27
+
class HalStorage::StorageLock {
28
+
public:
29
+
StorageLock() { xSemaphoreTake(HalStorage::getInstance().storageMutex, portMAX_DELAY); }
30
+
~StorageLock() { xSemaphoreGive(HalStorage::getInstance().storageMutex); }
31
+
};
32
+
33
+
#define HAL_STORAGE_WRAPPED_CALL(method, ...) \
34
+
HalStorage::StorageLock lock; \
35
+
return SDCard.method(__VA_ARGS__);
36
+
37
+
std::vector<String> HalStorage::listFiles(const char* path, int maxFiles) {
38
+
HAL_STORAGE_WRAPPED_CALL(listFiles, path, maxFiles);
39
+
}
40
+
41
+
String HalStorage::readFile(const char* path) { HAL_STORAGE_WRAPPED_CALL(readFile, path); }
18
42
19
43
bool HalStorage::readFileToStream(const char* path, Print& out, size_t chunkSize) {
20
-
return SDCard.readFileToStream(path, out, chunkSize);
44
+
HAL_STORAGE_WRAPPED_CALL(readFileToStream, path, out, chunkSize);
21
45
}
22
46
23
47
size_t HalStorage::readFileToBuffer(const char* path, char* buffer, size_t bufferSize, size_t maxBytes) {
24
-
return SDCard.readFileToBuffer(path, buffer, bufferSize, maxBytes);
48
+
HAL_STORAGE_WRAPPED_CALL(readFileToBuffer, path, buffer, bufferSize, maxBytes);
25
49
}
26
50
27
-
bool HalStorage::writeFile(const char* path, const String& content) { return SDCard.writeFile(path, content); }
51
+
bool HalStorage::writeFile(const char* path, const String& content) {
52
+
HAL_STORAGE_WRAPPED_CALL(writeFile, path, content);
53
+
}
28
54
29
-
bool HalStorage::ensureDirectoryExists(const char* path) { return SDCard.ensureDirectoryExists(path); }
55
+
bool HalStorage::ensureDirectoryExists(const char* path) { HAL_STORAGE_WRAPPED_CALL(ensureDirectoryExists, path); }
30
56
31
-
FsFile HalStorage::open(const char* path, const oflag_t oflag) { return SDCard.open(path, oflag); }
57
+
class HalFile::Impl {
58
+
public:
59
+
Impl(FsFile&& fsFile) : file(std::move(fsFile)) {}
60
+
FsFile file;
61
+
};
32
62
33
-
bool HalStorage::mkdir(const char* path, const bool pFlag) { return SDCard.mkdir(path, pFlag); }
63
+
HalFile::HalFile() = default;
34
64
35
-
bool HalStorage::exists(const char* path) { return SDCard.exists(path); }
65
+
HalFile::HalFile(std::unique_ptr<Impl> impl) : impl(std::move(impl)) {}
36
66
37
-
bool HalStorage::remove(const char* path) { return SDCard.remove(path); }
67
+
HalFile::~HalFile() = default;
38
68
39
-
bool HalStorage::rename(const char* oldPath, const char* newPath) { return SDCard.rename(oldPath, newPath); }
69
+
HalFile::HalFile(HalFile&&) = default;
40
70
41
-
bool HalStorage::rmdir(const char* path) { return SDCard.rmdir(path); }
71
+
HalFile& HalFile::operator=(HalFile&&) = default;
42
72
43
-
bool HalStorage::openFileForRead(const char* moduleName, const char* path, FsFile& file) {
44
-
return SDCard.openFileForRead(moduleName, path, file);
73
+
HalFile HalStorage::open(const char* path, const oflag_t oflag) {
74
+
StorageLock lock; // ensure thread safety for the duration of this function
75
+
return HalFile(std::make_unique<HalFile::Impl>(SDCard.open(path, oflag)));
45
76
}
46
77
47
-
bool HalStorage::openFileForRead(const char* moduleName, const std::string& path, FsFile& file) {
78
+
bool HalStorage::mkdir(const char* path, const bool pFlag) { HAL_STORAGE_WRAPPED_CALL(mkdir, path, pFlag); }
79
+
80
+
bool HalStorage::exists(const char* path) { HAL_STORAGE_WRAPPED_CALL(exists, path); }
81
+
82
+
bool HalStorage::remove(const char* path) { HAL_STORAGE_WRAPPED_CALL(remove, path); }
83
+
bool HalStorage::rename(const char* oldPath, const char* newPath) {
84
+
HAL_STORAGE_WRAPPED_CALL(rename, oldPath, newPath);
85
+
}
86
+
87
+
bool HalStorage::rmdir(const char* path) { HAL_STORAGE_WRAPPED_CALL(rmdir, path); }
88
+
89
+
bool HalStorage::openFileForRead(const char* moduleName, const char* path, HalFile& file) {
90
+
StorageLock lock; // ensure thread safety for the duration of this function
91
+
FsFile fsFile;
92
+
bool ok = SDCard.openFileForRead(moduleName, path, fsFile);
93
+
file = HalFile(std::make_unique<HalFile::Impl>(std::move(fsFile)));
94
+
return ok;
95
+
}
96
+
97
+
bool HalStorage::openFileForRead(const char* moduleName, const std::string& path, HalFile& file) {
48
98
return openFileForRead(moduleName, path.c_str(), file);
49
99
}
50
100
51
-
bool HalStorage::openFileForRead(const char* moduleName, const String& path, FsFile& file) {
101
+
bool HalStorage::openFileForRead(const char* moduleName, const String& path, HalFile& file) {
52
102
return openFileForRead(moduleName, path.c_str(), file);
53
103
}
54
104
55
-
bool HalStorage::openFileForWrite(const char* moduleName, const char* path, FsFile& file) {
56
-
return SDCard.openFileForWrite(moduleName, path, file);
105
+
bool HalStorage::openFileForWrite(const char* moduleName, const char* path, HalFile& file) {
106
+
StorageLock lock; // ensure thread safety for the duration of this function
107
+
FsFile fsFile;
108
+
bool ok = SDCard.openFileForWrite(moduleName, path, fsFile);
109
+
file = HalFile(std::make_unique<HalFile::Impl>(std::move(fsFile)));
110
+
return ok;
57
111
}
58
112
59
-
bool HalStorage::openFileForWrite(const char* moduleName, const std::string& path, FsFile& file) {
113
+
bool HalStorage::openFileForWrite(const char* moduleName, const std::string& path, HalFile& file) {
60
114
return openFileForWrite(moduleName, path.c_str(), file);
61
115
}
62
116
63
-
bool HalStorage::openFileForWrite(const char* moduleName, const String& path, FsFile& file) {
117
+
bool HalStorage::openFileForWrite(const char* moduleName, const String& path, HalFile& file) {
64
118
return openFileForWrite(moduleName, path.c_str(), file);
65
119
}
66
120
67
-
bool HalStorage::removeDir(const char* path) { return SDCard.removeDir(path); }
121
+
bool HalStorage::removeDir(const char* path) { HAL_STORAGE_WRAPPED_CALL(removeDir, path); }
122
+
123
+
// HalFile implementation
124
+
// Allow doing file operations while ensuring thread safety via HalStorage's mutex.
125
+
// Please keep the list below in sync with the HalFile.h header
126
+
127
+
#define HAL_FILE_WRAPPED_CALL(method, ...) \
128
+
HalStorage::StorageLock lock; \
129
+
assert(impl != nullptr); \
130
+
return impl->file.method(__VA_ARGS__);
131
+
132
+
#define HAL_FILE_FORWARD_CALL(method, ...) \
133
+
assert(impl != nullptr); \
134
+
return impl->file.method(__VA_ARGS__);
135
+
136
+
void HalFile::flush() { HAL_FILE_WRAPPED_CALL(flush, ); }
137
+
size_t HalFile::getName(char* name, size_t len) { HAL_FILE_WRAPPED_CALL(getName, name, len); }
138
+
size_t HalFile::size() { HAL_FILE_FORWARD_CALL(size, ); } // already thread-safe, no need to wrap
139
+
size_t HalFile::fileSize() { HAL_FILE_FORWARD_CALL(fileSize, ); } // already thread-safe, no need to wrap
140
+
bool HalFile::seek(size_t pos) { HAL_FILE_WRAPPED_CALL(seekSet, pos); }
141
+
bool HalFile::seekCur(int64_t offset) { HAL_FILE_WRAPPED_CALL(seekCur, offset); }
142
+
bool HalFile::seekSet(size_t offset) { HAL_FILE_WRAPPED_CALL(seekSet, offset); }
143
+
int HalFile::available() const { HAL_FILE_WRAPPED_CALL(available, ); }
144
+
size_t HalFile::position() const { HAL_FILE_WRAPPED_CALL(position, ); }
145
+
int HalFile::read(void* buf, size_t count) { HAL_FILE_WRAPPED_CALL(read, buf, count); }
146
+
int HalFile::read() { HAL_FILE_WRAPPED_CALL(read, ); }
147
+
size_t HalFile::write(const void* buf, size_t count) { HAL_FILE_WRAPPED_CALL(write, buf, count); }
148
+
size_t HalFile::write(uint8_t b) { HAL_FILE_WRAPPED_CALL(write, b); }
149
+
bool HalFile::rename(const char* newPath) { HAL_FILE_WRAPPED_CALL(rename, newPath); }
150
+
bool HalFile::isDirectory() const { HAL_FILE_FORWARD_CALL(isDirectory, ); } // already thread-safe, no need to wrap
151
+
void HalFile::rewindDirectory() { HAL_FILE_WRAPPED_CALL(rewindDirectory, ); }
152
+
bool HalFile::close() { HAL_FILE_WRAPPED_CALL(close, ); }
153
+
HalFile HalFile::openNextFile() {
154
+
HalStorage::StorageLock lock;
155
+
assert(impl != nullptr);
156
+
return HalFile(std::make_unique<Impl>(impl->file.openNextFile()));
157
+
}
158
+
bool HalFile::isOpen() const { return impl != nullptr && impl->file.isOpen(); } // already thread-safe, no need to wrap
159
+
HalFile::operator bool() const { return isOpen(); }
+60
-9
lib/hal/HalStorage.h
+60
-9
lib/hal/HalStorage.h
···
1
1
#pragma once
2
2
3
-
#include <FS.h> // need to be included before SdFat.h for compatibility with FS.h's File class
4
-
#include <SDCardManager.h>
3
+
#include <Print.h>
4
+
#include <common/FsApiConstants.h> // for oflag_t
5
+
#include <freertos/semphr.h>
5
6
7
+
#include <memory>
8
+
#include <string>
6
9
#include <vector>
10
+
11
+
class HalFile;
7
12
8
13
class HalStorage {
9
14
public:
···
25
30
// Ensure a directory exists, creating it if necessary. Returns true on success.
26
31
bool ensureDirectoryExists(const char* path);
27
32
28
-
FsFile open(const char* path, const oflag_t oflag = O_RDONLY);
33
+
HalFile open(const char* path, const oflag_t oflag = O_RDONLY);
29
34
bool mkdir(const char* path, const bool pFlag = true);
30
35
bool exists(const char* path);
31
36
bool remove(const char* path);
32
37
bool rename(const char* oldPath, const char* newPath);
33
38
bool rmdir(const char* path);
34
39
35
-
bool openFileForRead(const char* moduleName, const char* path, FsFile& file);
36
-
bool openFileForRead(const char* moduleName, const std::string& path, FsFile& file);
37
-
bool openFileForRead(const char* moduleName, const String& path, FsFile& file);
38
-
bool openFileForWrite(const char* moduleName, const char* path, FsFile& file);
39
-
bool openFileForWrite(const char* moduleName, const std::string& path, FsFile& file);
40
-
bool openFileForWrite(const char* moduleName, const String& path, FsFile& file);
40
+
bool openFileForRead(const char* moduleName, const char* path, HalFile& file);
41
+
bool openFileForRead(const char* moduleName, const std::string& path, HalFile& file);
42
+
bool openFileForRead(const char* moduleName, const String& path, HalFile& file);
43
+
bool openFileForWrite(const char* moduleName, const char* path, HalFile& file);
44
+
bool openFileForWrite(const char* moduleName, const std::string& path, HalFile& file);
45
+
bool openFileForWrite(const char* moduleName, const String& path, HalFile& file);
41
46
bool removeDir(const char* path);
42
47
43
48
static HalStorage& getInstance() { return instance; }
44
49
50
+
class StorageLock; // private class, used internally
51
+
45
52
private:
46
53
static HalStorage instance;
47
54
48
55
bool initialized = false;
56
+
SemaphoreHandle_t storageMutex = nullptr;
49
57
};
50
58
51
59
#define Storage HalStorage::getInstance()
60
+
61
+
class HalFile : public Print {
62
+
friend class HalStorage;
63
+
class Impl;
64
+
std::unique_ptr<Impl> impl;
65
+
explicit HalFile(std::unique_ptr<Impl> impl);
66
+
67
+
public:
68
+
HalFile();
69
+
~HalFile();
70
+
HalFile(HalFile&&);
71
+
HalFile& operator=(HalFile&&);
72
+
HalFile(const HalFile&) = delete;
73
+
HalFile& operator=(const HalFile&) = delete;
74
+
75
+
void flush();
76
+
size_t getName(char* name, size_t len);
77
+
size_t size();
78
+
size_t fileSize();
79
+
bool seek(size_t pos);
80
+
bool seekCur(int64_t offset);
81
+
bool seekSet(size_t offset);
82
+
int available() const;
83
+
size_t position() const;
84
+
int read(void* buf, size_t count);
85
+
int read(); // read a single byte
86
+
size_t write(const void* buf, size_t count);
87
+
size_t write(uint8_t b) override;
88
+
bool rename(const char* newPath);
89
+
bool isDirectory() const;
90
+
void rewindDirectory();
91
+
bool close();
92
+
HalFile openNextFile();
93
+
bool isOpen() const;
94
+
operator bool() const;
95
+
};
96
+
97
+
// Only do renaming FsFile to HalFile if this header is included by downstream code
98
+
// The renaming is to allow using the thread-safe HalFile instead of the raw FsFile, without needing to change the
99
+
// downstream code
100
+
#ifndef HAL_STORAGE_IMPL
101
+
using FsFile = HalFile;
102
+
#endif
52
103
53
104
// Downstream code must use Storage instead of SdMan
54
105
#ifdef SdMan