From 39fb4ab6f21871875d8570da1062dc2b397179f1 Mon Sep 17 00:00:00 2001 From: Erik Verbruggen Date: Fri, 21 Feb 2025 18:18:56 +0100 Subject: [PATCH] Add important documentation on the async nature of `Vfs::startImpl()` This is to inform/warn VFS implementors of the fact that starting the VFS implementation is assumed to possibly start in the background. But more importantly: the client will not "wait" for one VFS instance to be started before calling `start` on a second instance. Meaning: synchronization (when needed) has to be done by the VFS impementation itself. --- src/common/vfs.h | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/src/common/vfs.h b/src/common/vfs.h index dade2a7f831..2b2403ff3d8 100644 --- a/src/common/vfs.h +++ b/src/common/vfs.h @@ -155,6 +155,9 @@ class OCSYNC_EXPORT Vfs : public QObject /** Initializes interaction with the VFS provider. * * The plugin-specific work is done in startImpl(). + * + * \warning Please read the comments to \a startImpl() about the + * asynchronous behaviour! */ void start(const VfsSetupParams ¶ms); @@ -267,6 +270,16 @@ public Q_SLOTS: * * Usually some registration needs to be done with the backend. This function * should take care of it if necessary. + * + * \note The implementation is allowed to run asynchronously, meaning the method + * can return before the start is fully complete. On completion, the + * \a started() signal is emitted. + * \warning For VFS implementations: the rest of the code in the client assumes + * that it is safe to do multiple calls to this method, EVEN IF A PREVIOUS + * START IS NOT FULLY FINISHED. If ANY synchronization needs to be done + * (e.g. reading/writing to the Windows registry, or searching for + * StorageProvider information), this has to be implemented in the + * plugin itself. */ virtual void startImpl(const VfsSetupParams ¶ms) = 0;