File Operations

Overview

Note developers can easily plugin their own implementation to replace the underneath implementation of these primitives.

Classes
struct	dsn_file_buffer_t

Typedefs
typedef enum dsn_ctrl_code_t	dsn_ctrl_code_t

Enumerations
enum	dsn_ctrl_code_t { CTL_BATCH_INVALID = 0, CTL_BATCH_WRITE = 1, CTL_MAX_CON_READ_OP_COUNT = 2, CTL_MAX_CON_WRITE_OP_COUNT = 3 }

Functions
DSN_API dsn_handle_t	dsn_file_open (const char *file_name, int flag, int pmode)
DSN_API dsn_error_t	dsn_file_close (dsn_handle_t file)
DSN_API dsn_error_t	dsn_file_flush (dsn_handle_t file)
DSN_API void *	dsn_file_native_handle (dsn_handle_t file)
DSN_API dsn_task_t	dsn_file_create_aio_task (dsn_task_code_t code, dsn_aio_handler_t cb, void *context, int hash DEFAULT(0), dsn_task_tracker_t tracker DEFAULT(nullptr))
DSN_API dsn_task_t	dsn_file_create_aio_task_ex (dsn_task_code_t code, dsn_aio_handler_t cb, dsn_task_cancelled_handler_t on_cancel, void *context, int hash DEFAULT(0), dsn_task_tracker_t tracker DEFAULT(nullptr))
DSN_API void	dsn_file_read (dsn_handle_t file, char *buffer, int count, uint64_t offset, dsn_task_t cb)
DSN_API void	dsn_file_write (dsn_handle_t file, const char *buffer, int count, uint64_t offset, dsn_task_t cb)
DSN_API void	dsn_file_write_vector (dsn_handle_t file, const dsn_file_buffer_t *buffers, int buffer_count, uint64_t offset, dsn_task_t cb)
DSN_API void	dsn_file_copy_remote_directory (dsn_address_t remote, const char *source_dir, const char *dest_dir, bool overwrite, dsn_task_t cb)
DSN_API void	dsn_file_copy_remote_files (dsn_address_t remote, const char *source_dir, const char **source_files, const char *dest_dir, bool overwrite, dsn_task_t cb)
DSN_API size_t	dsn_file_get_io_size (dsn_task_t cb_task)
DSN_API void	dsn_file_task_enqueue (dsn_task_t cb_task, dsn_error_t err, size_t size)

Typedef Documentation

typedef enum dsn_ctrl_code_t dsn_ctrl_code_t

the following ctrl code are used by dsn_file_ctrl.

Enumeration Type Documentation

enum dsn_ctrl_code_t

the following ctrl code are used by dsn_file_ctrl.

Enumerator
CTL_BATCH_WRITE	(batch) set write batch size
CTL_MAX_CON_READ_OP_COUNT	(throttling) maximum concurrent read ops
CTL_MAX_CON_WRITE_OP_COUNT	(throttling) maximum concurrent write ops

Function Documentation

DSN_API dsn_handle_t dsn_file_open	(	const char *	file_name,
		int	flag,
		int	pmode
	)

open file

Parameters

file_name	filename of the file.
flag	flags such as O_RDONLY | O_BINARY used by ::open
pmode	permission mode used by ::open

Returns

file handle

DSN_API dsn_task_t dsn_file_create_aio_task	(	dsn_task_code_t	code,
		dsn_aio_handler_t	cb,
		void *	context,
		int hash	DEFAULT0,
		dsn_task_tracker_t tracker	DEFAULTnullptr
	)

create aio task which is executed on completion of the file operations

Parameters

code	task code
cb	callback to be executed
context	context used by cb
hash	specify which thread to execute cb if target pool is partitioned
tracker	task tracker bound to this aio task

Returns

aio task handle, nullptr for failure

DSN_API dsn_task_t dsn_file_create_aio_task_ex	(	dsn_task_code_t	code,
		dsn_aio_handler_t	cb,
		dsn_task_cancelled_handler_t	on_cancel,
		void *	context,
		int hash	DEFAULT0,
		dsn_task_tracker_t tracker	DEFAULTnullptr
	)

create aio task which is executed on completion of the file operations

Parameters

code	task code
cb	callback to be executed on task completion
on_cancel	callback to be executed on task being-cancelled
context	context used by cb
hash	specify which thread to execute cb if target pool is partitioned
tracker	task tracker bound to this aio task

Returns

aio task handle, nullptr for failure

DSN_API void dsn_file_read	(	dsn_handle_t	file,
		char *	buffer,
		int	count,
		uint64_t	offset,
		dsn_task_t	cb
	)

read file asynchronously

Parameters

file	file handle
buffer	read buffer
count	byte size of the read buffer
offset	offset in the file to start reading
cb	callback aio task to be executed on completion

DSN_API void dsn_file_write	(	dsn_handle_t	file,
		const char *	buffer,
		int	count,
		uint64_t	offset,
		dsn_task_t	cb
	)

write file asynchronously

Parameters

file	file handle
buffer	write buffer
count	byte size of the to-be-written content
offset	offset in the file to start write
cb	callback aio task to be executed on completion

DSN_API void dsn_file_write_vector	(	dsn_handle_t	file,
		const dsn_file_buffer_t *	buffers,
		int	buffer_count,
		uint64_t	offset,
		dsn_task_t	cb
	)

write file asynchronously with vector buffers

Parameters

file	file handle
buffers	write buffers
buffer_count	number of write buffers
offset	offset in the file to start write
cb	callback aio task to be executed on completion

DSN_API void dsn_file_copy_remote_directory	(	dsn_address_t	remote,
		const char *	source_dir,
		const char *	dest_dir,
		bool	overwrite,
		dsn_task_t	cb
	)

copy remote directory to the local machine

Parameters

remote	address of the remote nfs server
source_dir	source dir on remote server
dest_dir	destination dir on local server
overwrite	true to overwrite, false to preserve.
cb	callback aio task to be executed on completion

DSN_API void dsn_file_copy_remote_files	(	dsn_address_t	remote,
		const char *	source_dir,
		const char **	source_files,
		const char *	dest_dir,
		bool	overwrite,
		dsn_task_t	cb
	)

copy remote files to the local machine

Parameters

remote	address of the remote nfs server
source_dir	source dir on remote server
source_files	zero-ended file string array within the source dir on remote server, when it contains no files, all files within source_dir are copied
dest_dir	destination dir on local server
overwrite	true to overwrite, false to preserve.
cb	callback aio task to be executed on completion