docs(io): say what can block when building an S3 client

Two comments said building an S3 client can look up a bucket region. It
does not here: Arrow resolves a bucket's region only in
S3Options::FromUri, which this code does not use. What can block is the
AWS SDK waiting on the EC2 metadata service when no static keys are set
(about 4 s per build off EC2); a build from static keys does not wait.

Author: plusplusjiajia

src/iceberg/arrow/s3/arrow_s3_file_io.cc

@@ -221,9 +221,9 @@ class ArrowS3FileIO final : public FileIO, public SupportsStorageCredentials {
 
   /// \brief Build a delegate for each credential this FileIO can serve.
   ///
-  /// Runs without holding `mutex_`: building an S3 client can reach out to discover a
-  /// bucket region, which would stall every concurrent operation. Reads no
-  /// mutable member state.
+  /// Runs without holding `mutex_`: building an S3 client can block (without
+  /// static keys the AWS SDK may wait on the EC2 metadata service), which would
+  /// stall every concurrent operation. Reads no mutable member state.
   Result<DelegatesByPrefix> BuildDelegates(
       const std::vector<StorageCredential>& storage_credentials) const;
 

src/iceberg/resolving_file_io.cc

@@ -40,10 +40,10 @@ Result<std::shared_ptr<FileIO>> ResolvingFileIO::FileIOForPath(
   const auto scheme = StringUtils::ToLower(LocationUtil::ParseScheme(location));
   ICEBERG_ASSIGN_OR_RAISE(const auto name, FileIORegistry::Resolve(scheme));
 
-  // Loads without holding `mutex_`: building a client can reach the network (an
-  // S3 client may look up its bucket region), which would stall every other
-  // operation. Forwards all credentials; each implementation applies the
-  // prefixes it understands.
+  // Loads without holding `mutex_`: building a client can block (an S3 client
+  // without static keys may wait on the EC2 metadata service), which would
+  // stall every other operation. Forwards all credentials; each implementation
+  // applies the prefixes it understands.
   auto load = [&](const std::vector<StorageCredential>& credentials)
       -> Result<std::shared_ptr<FileIO>> {
     ICEBERG_ASSIGN_OR_RAISE(std::shared_ptr<FileIO> io,