WiredTiger: WT_FILE_HANDLE Struct Reference

| Version 3.1.0

Fork me on GitHub Join my user group
List of all members | Public Attributes
WT_FILE_HANDLE Struct Reference
WiredTiger Extension API

A file handle implementation returned by WT_FILE_SYSTEM::open_file. More...

## Public Attributes
WT_FILE_SYSTEM * | file_system
| The enclosing file system, set by WT_FILE_SYSTEM::open_file.
char * | name
| The name of the file, set by WT_FILE_SYSTEM::open_file.
int(* | close )(WT_FILE_HANDLE *file_handle, WT_SESSION *session)
| Close a file handle, the handle will not be further accessed by WiredTiger. More...
int(* | fh_advise )(WT_FILE_HANDLE *file_handle, WT_SESSION *session, wt_off_t offset, wt_off_t len, int advice)
| Indicate expected future use of file ranges, based on the POSIX 1003.1 standard fadvise. More...
int(* | fh_extend )(WT_FILE_HANDLE *file_handle, WT_SESSION *session, wt_off_t offset)
| Extend the file. More...
int(* | fh_extend_nolock )(WT_FILE_HANDLE *file_handle, WT_SESSION *session, wt_off_t offset)
| Extend the file. More...
int(* | fh_lock )(WT_FILE_HANDLE *file_handle, WT_SESSION *session, bool lock)
| Lock/unlock a file from the perspective of other processes running in the system, where necessary. More...
int(* | fh_map )(WT_FILE_HANDLE *file_handle, WT_SESSION *session, void *mapped_regionp, size_t *lengthp, void *mapped_cookiep)
| Map a file into memory, based on the POSIX 1003.1 standard mmap. More...
int(* | fh_map_discard )(WT_FILE_HANDLE *file_handle, WT_SESSION *session, void *map, size_t length, void *mapped_cookie)
| Unmap part of a memory mapped file, based on the POSIX 1003.1 standard madvise. More...
int(* | fh_map_preload )(WT_FILE_HANDLE *file_handle, WT_SESSION *session, const void *map, size_t length, void *mapped_cookie)
| Preload part of a memory mapped file, based on the POSIX 1003.1 standard madvise. More...
int(* | fh_unmap )(WT_FILE_HANDLE *file_handle, WT_SESSION *session, void *mapped_region, size_t length, void *mapped_cookie)
| Unmap a memory mapped file, based on the POSIX 1003.1 standard munmap. More...
int(* | fh_read )(WT_FILE_HANDLE *file_handle, WT_SESSION *session, wt_off_t offset, size_t len, void *buf)
| Read from a file, based on the POSIX 1003.1 standard pread. More...
int(* | fh_size )(WT_FILE_HANDLE *file_handle, WT_SESSION *session, wt_off_t *sizep)
| Return the size of a file. More...
int(* | fh_sync )(WT_FILE_HANDLE *file_handle, WT_SESSION *session)
| Make outstanding file writes durable and do not return until writes are complete. More...
int(* | fh_sync_nowait )(WT_FILE_HANDLE *file_handle, WT_SESSION *session)
| Schedule the outstanding file writes required for durability and return immediately. More...
int(* | fh_truncate )(WT_FILE_HANDLE *file_handle, WT_SESSION *session, wt_off_t offset)
| Truncate the file. More...
int(* | fh_write )(WT_FILE_HANDLE *file_handle, WT_SESSION *session, wt_off_t offset, size_t length, const void *buf)
| Write to a file, based on the POSIX 1003.1 standard pwrite. More...

## Detailed Description

A file handle implementation returned by WT_FILE_SYSTEM::open_file.

Thread safety: Unless explicitly stated otherwise, WiredTiger may invoke methods on the WT_FILE_HANDLE interface from multiple threads concurrently. It is the responsibility of the implementation to protect any shared data.

See Custom File Systems for more information.

Examples:
  ex_file_system.c.

## Member Data Documentation

## ◆ close

int(* WT_FILE_HANDLE::close) (WT_FILE_HANDLE *file_handle, WT_SESSION *session)

Close a file handle, the handle will not be further accessed by WiredTiger.

Returns
  zero on success and a non-zero error code on failure. See Error handling for details.

Parameters

  file_handle | the WT_FILE_HANDLE
  session | the current WiredTiger session

Examples:
  ex_file_system.c.

## ◆ fh_advise

int(* WT_FILE_HANDLE::fh_advise) (WT_FILE_HANDLE *file_handle, WT_SESSION *session, wt_off_t offset, wt_off_t len, int advice)

Indicate expected future use of file ranges, based on the POSIX 1003.1 standard fadvise.

This method is not required, and should be set to NULL when not supported by the file.

Returns
  zero on success and a non-zero error code on failure. See Error handling for details.

Parameters

  file_handle | the WT_FILE_HANDLE
  session | the current WiredTiger session
  offset | the file offset
  len | the size of the advisory
  advice | one of WT_FILE_HANDLE_WILLNEED or WT_FILE_HANDLE_DONTNEED.

Examples:
  ex_file_system.c.

## ◆ fh_extend

int(* WT_FILE_HANDLE::fh_extend) (WT_FILE_HANDLE *file_handle, WT_SESSION *session, wt_off_t offset)

Extend the file.

This method is not required, and should be set to NULL when not supported by the file.

Any allocated disk space must read as 0 bytes, and no existing file data may change. Allocating all necessary underlying storage (not changing just the file's metadata), is likely to result in increased performance.

This method is not called by multiple threads concurrently (on the same file handle). If the file handle's extension method supports concurrent calls, set the WT_FILE_HANDLE::fh_extend_nolock method instead. See Custom File Systems for more information.

Returns
  zero on success and a non-zero error code on failure. See Error handling for details.

Parameters

  file_handle | the WT_FILE_HANDLE
  session | the current WiredTiger session
  offset | desired file size after extension

Examples:
  ex_file_system.c.

## ◆ fh_extend_nolock

int(* WT_FILE_HANDLE::fh_extend_nolock) (WT_FILE_HANDLE *file_handle, WT_SESSION *session, wt_off_t offset)

Extend the file.

This method is not required, and should be set to NULL when not supported by the file.

Any allocated disk space must read as 0 bytes, and no existing file data may change. Allocating all necessary underlying storage (not only changing the file's metadata), is likely to result in increased performance.

This method may be called by multiple threads concurrently (on the same file handle). If the file handle's extension method does not support concurrent calls, set the WT_FILE_HANDLE::fh_extend method instead. See Custom File Systems for more information.

Returns
  zero on success and a non-zero error code on failure. See Error handling for details.

Parameters

  file_handle | the WT_FILE_HANDLE
  session | the current WiredTiger session
  offset | desired file size after extension

Examples:
  ex_file_system.c.

## ◆ fh_lock

int(* WT_FILE_HANDLE::fh_lock) (WT_FILE_HANDLE *file_handle, WT_SESSION *session, bool lock)

Lock/unlock a file from the perspective of other processes running in the system, where necessary.

Returns
  zero on success and a non-zero error code on failure. See Error handling for details.

Parameters

  file_handle | the WT_FILE_HANDLE
  session | the current WiredTiger session
  lock | whether to lock or unlock

Examples:
  ex_file_system.c.

## ◆ fh_map

int(* WT_FILE_HANDLE::fh_map) (WT_FILE_HANDLE *file_handle, WT_SESSION *session, void *mapped_regionp, size_t *lengthp, void *mapped_cookiep)

Map a file into memory, based on the POSIX 1003.1 standard mmap.

This method is not required, and should be set to NULL when not supported by the file.

Returns
  zero on success and a non-zero error code on failure. See Error handling for details.

Parameters

  | file_handle | the WT_FILE_HANDLE
  | session | the current WiredTiger session
  [out] | mapped_regionp | a reference to a memory location into which should be stored a pointer to the start of the mapped region
  [out] | lengthp | a reference to a memory location into which should be stored the length of the region
  [out] | mapped_cookiep | a reference to a memory location into which can be optionally stored a pointer to an opaque cookie which is subsequently passed to WT_FILE_HANDLE::unmap.

Examples:
  ex_file_system.c.

## ◆ fh_map_discard

int(* WT_FILE_HANDLE::fh_map_discard) (WT_FILE_HANDLE *file_handle, WT_SESSION *session, void *map, size_t length, void *mapped_cookie)

Unmap part of a memory mapped file, based on the POSIX 1003.1 standard madvise.

This method is not required, and should be set to NULL when not supported by the file.

Returns
  zero on success and a non-zero error code on failure. See Error handling for details.

Parameters

  file_handle | the WT_FILE_HANDLE
  session | the current WiredTiger session
  map | a location in the mapped region unlikely to be used in the near future
  length | the length of the mapped region to discard
  mapped_cookie | any cookie set by the WT_FILE_HANDLE::map method

Examples:
  ex_file_system.c.

## ◆ fh_map_preload

int(* WT_FILE_HANDLE::fh_map_preload) (WT_FILE_HANDLE *file_handle, WT_SESSION *session, const void *map, size_t length, void *mapped_cookie)

Preload part of a memory mapped file, based on the POSIX 1003.1 standard madvise.

This method is not required, and should be set to NULL when not supported by the file.

Returns
  zero on success and a non-zero error code on failure. See Error handling for details.

Parameters

  file_handle | the WT_FILE_HANDLE
  session | the current WiredTiger session
  map | a location in the mapped region likely to be used in the near future
  length | the size of the mapped region to preload
  mapped_cookie | any cookie set by the WT_FILE_HANDLE::map method

Examples:
  ex_file_system.c.

## ◆ fh_read

int(* WT_FILE_HANDLE::fh_read) (WT_FILE_HANDLE *file_handle, WT_SESSION *session, wt_off_t offset, size_t len, void *buf)

Read from a file, based on the POSIX 1003.1 standard pread.

Returns
  zero on success and a non-zero error code on failure. See Error handling for details.

Parameters

  | file_handle | the WT_FILE_HANDLE
  | session | the current WiredTiger session
  | offset | the offset in the file to start reading from
  | len | the amount to read
  [out] | buf | buffer to hold the content read from file

Examples:
  ex_file_system.c.

## ◆ fh_size

int(* WT_FILE_HANDLE::fh_size) (WT_FILE_HANDLE *file_handle, WT_SESSION *session, wt_off_t *sizep)

Return the size of a file.

Returns
  zero on success and a non-zero error code on failure. See Error handling for details.

Parameters

  file_handle | the WT_FILE_HANDLE
  session | the current WiredTiger session
  sizep | the size of the file

Examples:
  ex_file_system.c.

## ◆ fh_sync

int(* WT_FILE_HANDLE::fh_sync) (WT_FILE_HANDLE *file_handle, WT_SESSION *session)

Make outstanding file writes durable and do not return until writes are complete.

This method is not required for read-only files, and should be set to NULL when not supported by the file.

Returns
  zero on success and a non-zero error code on failure. See Error handling for details.

Parameters

  file_handle | the WT_FILE_HANDLE
  session | the current WiredTiger session

Examples:
  ex_file_system.c.

## ◆ fh_sync_nowait

int(* WT_FILE_HANDLE::fh_sync_nowait) (WT_FILE_HANDLE *file_handle, WT_SESSION *session)

Schedule the outstanding file writes required for durability and return immediately.

This method is not required, and should be set to NULL when not supported by the file.

Returns
  zero on success and a non-zero error code on failure. See Error handling for details.

Parameters

  file_handle | the WT_FILE_HANDLE
  session | the current WiredTiger session

Examples:
  ex_file_system.c.

## ◆ fh_truncate

int(* WT_FILE_HANDLE::fh_truncate) (WT_FILE_HANDLE *file_handle, WT_SESSION *session, wt_off_t offset)

Truncate the file.

This method is not required, and should be set to NULL when not supported by the file.

This method is not called by multiple threads concurrently (on the same file handle).

Returns
  zero on success and a non-zero error code on failure. See Error handling for details.

Parameters

  file_handle | the WT_FILE_HANDLE
  session | the current WiredTiger session
  offset | desired file size after truncate

Examples:
  ex_file_system.c.

## ◆ fh_unmap

int(* WT_FILE_HANDLE::fh_unmap) (WT_FILE_HANDLE *file_handle, WT_SESSION *session, void *mapped_region, size_t length, void *mapped_cookie)

Unmap a memory mapped file, based on the POSIX 1003.1 standard munmap.

This method is only required if a valid implementation of map is provided by the file, and should be set to NULL otherwise.

Returns
  zero on success and a non-zero error code on failure. See Error handling for details.

Parameters

  file_handle | the WT_FILE_HANDLE
  session | the current WiredTiger session
  mapped_region | a pointer to the start of the mapped region
  length | the length of the mapped region
  mapped_cookie | any cookie set by the WT_FILE_HANDLE::map method

Examples:
  ex_file_system.c.

## ◆ fh_write

int(* WT_FILE_HANDLE::fh_write) (WT_FILE_HANDLE *file_handle, WT_SESSION *session, wt_off_t offset, size_t length, const void *buf)

Write to a file, based on the POSIX 1003.1 standard pwrite.

This method is not required for read-only files, and should be set to NULL when not supported by the file.

Returns
  zero on success and a non-zero error code on failure. See Error handling for details.

Parameters

  file_handle | the WT_FILE_HANDLE
  session | the current WiredTiger session
  offset | offset at which to start writing
  length | amount of data to write
  buf | content to be written to the file

Examples:
  ex_file_system.c.