pub struct FileHandle<'fs> { /* private fields */ }Expand description
RAII wrapper for an open duckdb_file_handle.
Automatically closed and destroyed when dropped.
§Lifetime
A handle refers to the database’s underlying file system: once the
database is closed (duckdb_close on the last reference), every method is
a use-after-free — valgrind reports an invalid read in
duckdb::FileHandle::Read. The handle therefore borrows the
FileSystem that opened it for 'fs, which in turn borrows the
ClientContext whose contract keeps the connection (and so the
database) open. Using a handle after its file system is gone does not
compile:
use quack_rs::client_context::ClientContext;
use quack_rs::file_system::{FileOpenOptions, FileSystem};
fn demo(ctx: &ClientContext) {
let fs = FileSystem::from_client_context(ctx).unwrap();
let handle = fs.open(c"data.csv", &FileOpenOptions::read_only()).unwrap();
drop(fs); // error[E0505]: cannot move out of `fs` because it is borrowed
let _ = handle.size();
}§Threads
A FileHandle is Send: it may be moved to, used on and dropped on
another thread. It is not Sync, so two threads cannot use one at
the same time; share it behind a Mutex. See the
unsafe impl Send below for the reasoning.
fn assert_sync<T: Sync>() {}
assert_sync::<quack_rs::file_system::FileHandle<'static>>();§Keeping a file open across callbacks
A COPY ... TO writer opens its file in global_init, writes it in
sink and closes it in finalize, so the handle has to live in the
statement’s global state, which is 'static and shared by every sink
thread. The borrow above cannot express that the state is destroyed while
the statement — and so the connection and database — are still alive, so
end it explicitly, once, and keep the handle in a Mutex:
use std::sync::Mutex;
use quack_rs::copy_function::CopyGlobalInitInfo;
use quack_rs::file_system::{FileHandle, FileOpenOptions, FileSystem};
struct Writer {
file: Mutex<FileHandle<'static>>,
}
// SAFETY: the context is only used inside this callback.
let ctx = unsafe { info.get_client_context() };
let fs = FileSystem::from_client_context(&ctx).ok_or("no file system")?;
// SAFETY: DuckDB copies the path out before the callback returns.
let path = unsafe { info.get_file_path() }.map_err(|e| e.to_string())?;
let path = std::ffi::CString::new(path).map_err(|e| e.to_string())?;
let file = fs.open(&path, &FileOpenOptions::write_create()).map_err(|e| e.to_string())?;
// SAFETY: the handle ends up in this statement's global state, which
// DuckDB destroys before the statement finishes, while the connection and
// the database it was opened against are still open.
let file: FileHandle<'static> = unsafe { FileHandle::from_raw(file.into_raw()) };
info.set_global_state_typed(Writer { file: Mutex::new(file) });sink then reads it with global_state_ref::<Writer>() and locks the
mutex to write; dropping the state closes the file.
Implementations§
Source§impl FileHandle<'_>
impl FileHandle<'_>
Sourcepub const unsafe fn from_raw(handle: duckdb_file_handle) -> Self
pub const unsafe fn from_raw(handle: duckdb_file_handle) -> Self
Wraps a raw duckdb_file_handle, taking ownership.
§Safety
handle must be a valid, non-null duckdb_file_handle that the caller no
longer manages, and the database it was opened against must stay open
for the whole of the lifetime the caller picks for the result.
Sourcepub const fn into_raw(self) -> duckdb_file_handle
pub const fn into_raw(self) -> duckdb_file_handle
Consumes the FileHandle and returns the raw handle without closing
it, the inverse of from_raw.
The caller takes over closing (duckdb_file_handle_close) and
destroying (duckdb_destroy_file_handle) it — or hands it back to
from_raw, which is how a handle is moved into state that outlives
this borrow (see Keeping a file open across
callbacks).
Sourcepub fn read_exact(&self, buf: &mut [u8]) -> Result<(), ErrorData>
pub fn read_exact(&self, buf: &mut [u8]) -> Result<(), ErrorData>
Reads exactly buf.len() bytes, or fails.
duckdb_file_handle_read returns “the number of bytes actually
read”, so a single read can come up short on any file system — and
httpfs is exactly where that happens. This loops until the buffer is
full.
§Errors
Returns the structured ErrorData on read failure, or a
DuckDbErrorType::Io error if
the file ends before buf is filled.
Sourcepub fn write_all(&self, buf: &[u8]) -> Result<(), ErrorData>
pub fn write_all(&self, buf: &[u8]) -> Result<(), ErrorData>
Writes all of buf, or fails.
Like read_exact, this exists because
duckdb_file_handle_write reports the number of bytes actually
written.
§Errors
Returns the structured ErrorData on write failure, or a
DuckDbErrorType::Io error if
DuckDB stops accepting bytes before the buffer is drained.
Sourcepub fn error_data(&self) -> ErrorData
pub fn error_data(&self) -> ErrorData
Returns the structured error from the most recent failed operation.