bkietz commented on code in PR #39067:
URL: https://github.com/apache/arrow/pull/39067#discussion_r1516437184
##########
docs/source/cpp/io.rst:
##########
@@ -91,4 +101,46 @@ Concrete implementations are available for
Tasks that use filesystems will typically run on the
:ref:`I/O thread pool<io_thread_pool>`. For filesystems that support high
levels
- of concurrency you may get a benefit from increasing the size of the I/O
thread pool.
\ No newline at end of file
+ of concurrency you may get a benefit from increasing the size of the I/O
thread pool.
+
+Defining new FileSystems
+========================
+
+Support for additional URI schemes can be added to the
+:ref:`FromUri factories <filesystem-factory-functions>`
+by registering a factory for each new URI scheme with
+:func:`~arrow::fs::RegisterFileSystemFactory`. To enable the common case
+wherein it is preferred that registration be automatic, an instance of
+:class:`~arrow::fs::FileSystemRegistrar` can be defined at namespace
+scope, which will register a factory whenever the instance is loaded:
+
+.. code-block:: cpp
+
+ arrow::fs::FileSystemRegistrar kExampleFileSystemModule{
+ "example",
+ [](const Uri& uri, const io::IOContext& io_context,
+ std::string* out_path) ->
Result<std::shared_ptr<arrow::fs::FileSystem>> {
+ EnsureExampleFileSystemInitialized();
+ return std::make_shared<ExampleFileSystem>();
+ },
+ &EnsureExampleFileSystemFinalized,
+ };
+
+If a filesystem implementation requires initialization before any instances
+may be constructed, this should be included in the corresponding factory or
+otherwise automatically ensured before the factory is invoked. Likewise if
+a filesystem implementation requires tear down before the process ends, this
+can be wrapped in a function and registered alongside the factory. All
+finalizers will be called by :func:`~arrow::fs::EnsureFinalized`.
+
+Build complexity can be decreased by compartmentalizing a FileSystem
+implementation into a separate shared library, which applications may
+link or load dynamically. Arrow's built-in FileSystem implementations
+also follow this pattern. If a shared library containing instances of
+:class:`~arrow::fs::FileSystemRegistrar` must be dynamically loaded,
+:func:`~arrow::fs::LoadFileSystemFactories` should be used to load it.
+Such a library should have exactly one of its sources
+``#include "arrow/filesystem/filesystem_library.h"``
Review Comment:
It should not be required if the library links dynamically to arrow, I'll
repeat that here
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
