src/iceberg/arrow/arrow_io_util.h

/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */

#pragma once

/// \file iceberg/arrow/arrow_io_util.h
/// \brief Provide helpers to create Arrow-backed FileIO implementations.

#include <memory>
#include <string>
#include <unordered_map>

#include "iceberg/file_io.h"
#include "iceberg/iceberg_bundle_export.h"
#include "iceberg/result.h"
#include "iceberg/type_fwd.h"

namespace iceberg::arrow {

ICEBERG_BUNDLE_EXPORT std::unique_ptr<FileIO> MakeMockFileIO();

ICEBERG_BUNDLE_EXPORT std::unique_ptr<FileIO> MakeLocalFileIO();

/// \brief Create an S3 FileIO backed by Arrow's S3FileSystem.
///
/// This function initializes the S3 subsystem if not already initialized (thread-safe).
/// The S3 initialization is cached once per process.
///
/// \param properties Configuration properties for S3 access. See S3Properties
///        for available keys (credentials, region, endpoint, timeouts, etc.).
/// \return A FileIO instance for S3 operations, or an error if S3 is not supported.
ICEBERG_BUNDLE_EXPORT Result<std::unique_ptr<FileIO>> MakeS3FileIO(
    const std::unordered_map<std::string, std::string>& properties = {});

/// \brief Initialize the shared executor for S3 bulk deletes.
///
/// nullptr runs sequentially. The first delete freezes this default if not initialized.
/// Repeating the same executor is allowed; replacing it is not. The caller owns it
/// and must keep it alive until the last delete completes. Includes registry-created
/// FileIOs. See Executor for blocking requirements.
ICEBERG_BUNDLE_EXPORT Status InitializeS3FileIODeleteExecutor(Executor* executor);

/// \brief Finalize (clean up) the Arrow S3 subsystem.
///
/// Must be called before process exit if S3 was initialized, otherwise Arrow's
/// static destructors may cause a non-zero exit.
ICEBERG_BUNDLE_EXPORT Status FinalizeS3();

}  // namespace iceberg::arrow