diff options
Diffstat (limited to 'include/iprt/aiomgr.h')
| -rw-r--r-- | include/iprt/aiomgr.h | 166 |
1 files changed, 166 insertions, 0 deletions
diff --git a/include/iprt/aiomgr.h b/include/iprt/aiomgr.h new file mode 100644 index 00000000..d7bef23f --- /dev/null +++ b/include/iprt/aiomgr.h @@ -0,0 +1,166 @@ +/** @file + * IPRT - Async I/O manager. + */ + +/* + * Copyright (C) 2013-2019 Oracle Corporation + * + * This file is part of VirtualBox Open Source Edition (OSE), as + * available from http://www.virtualbox.org. This file is free software; + * you can redistribute it and/or modify it under the terms of the GNU + * General Public License (GPL) as published by the Free Software + * Foundation, in version 2 as it comes in the "COPYING" file of the + * VirtualBox OSE distribution. VirtualBox OSE is distributed in the + * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind. + * + * The contents of this file may alternatively be used under the terms + * of the Common Development and Distribution License Version 1.0 + * (CDDL) only, as it comes in the "COPYING.CDDL" file of the + * VirtualBox OSE distribution, in which case the provisions of the + * CDDL are applicable instead of those of the GPL. + * + * You may elect to license modified versions of this file under the + * terms and conditions of either the GPL or the CDDL or both. + */ + +#ifndef IPRT_INCLUDED_aiomgr_h +#define IPRT_INCLUDED_aiomgr_h +#ifndef RT_WITHOUT_PRAGMA_ONCE +# pragma once +#endif + +#include <iprt/cdefs.h> +#include <iprt/types.h> +#include <iprt/sg.h> + + +RT_C_DECLS_BEGIN + +/** @defgroup grp_rt_aiomgr RTAioMgr - Async I/O Manager. + * @ingroup grp_rt + * @{ + */ + +/** + * Completion callback. + * + * @returns nothing. + * @param hAioMgrFile File handle the completed request was for. + * @param rcReq Status code of the completed request. + * @param pvUser Opaque user data given when the request was initiated. + */ +typedef DECLCALLBACK(void) FNRTAIOMGRREQCOMPLETE(RTAIOMGRFILE hAioMgrFile, int rcReq, void *pvUser); +/** Pointer to a completion callback. */ +typedef FNRTAIOMGRREQCOMPLETE *PFNRTAIOMGRREQCOMPLETE; + +/** + * Create a new async I/O manager. + * + * @returns IPRT statuse code. + * @param phAioMgr Where to store the new async I/O manager handle on success. + * @param cReqsMax Maximum number of async I/O requests expected. + * Use UINT32_MAX to make it grow dynamically when required. + */ +RTDECL(int) RTAioMgrCreate(PRTAIOMGR phAioMgr, uint32_t cReqsMax); + +/** + * Retain a async I/O manager handle. + * + * @returns New reference count on success, UINT32_MAX on failure. + * @param hAioMgr The async I/O manager to retain. + */ +RTDECL(uint32_t) RTAioMgrRetain(RTAIOMGR hAioMgr); + +/** + * Releases a async I/O manager handle. + * + * @returns New reference count on success (0 if closed), UINT32_MAX on failure. + * @param hAioMgr The async I/O manager to release. + */ +RTDECL(uint32_t) RTAioMgrRelease(RTAIOMGR hAioMgr); + +/** + * Assign a given file handle to the given async I/O manager. + * + * @returns IPRT status code. + * @param hAioMgr Async I/O manager handle. + * @param hFile File handle to assign. + * @param pfnReqComplete Callback to execute whenever a request for the + * file completed. + * @param phAioMgrFile Where to store the newly created async I/O manager + * handle on success. + * @param pvUser Opaque user data for this file handle. + * + * @note This function increases the reference count of the given async I/O manager + * by 1. + */ +RTDECL(int) RTAioMgrFileCreate(RTAIOMGR hAioMgr, RTFILE hFile, PFNRTAIOMGRREQCOMPLETE pfnReqComplete, + void *pvUser, PRTAIOMGRFILE phAioMgrFile); + +/** + * Retain a async I/O manager file handle. + * + * @returns New reference count on success, UINT32_MAX on failure. + * @param hAioMgrFile The file handle to retain. + */ +RTDECL(uint32_t) RTAioMgrFileRetain(RTAIOMGRFILE hAioMgrFile); + +/** + * Releases a async I/O manager file handle. + * + * @returns New reference count on success (0 if closed), UINT32_MAX on failure. + * @param hAioMgrFile The file handle to release. + */ +RTDECL(uint32_t) RTAioMgrFileRelease(RTAIOMGRFILE hAioMgrFile); + +/** + * Return opaque user data passed on creation. + * + * @returns Opaque user data or NULL if the handle is invalid. + * @param hAioMgrFile The file handle. + */ +RTDECL(void *) RTAioMgrFileGetUser(RTAIOMGRFILE hAioMgrFile); + +/** + * Initiate a read request from the given file handle. + * + * @returns IPRT status code. + * @param hAioMgrFile The file handle to read from. + * @param off Start offset to read from. + * @param pSgBuf S/G buffer to read into. The buffer is advanced + * by the amount of data to read. + * @param cbRead Number of bytes to read. + * @param pvUser Opaque user data given in the completion callback. + */ +RTDECL(int) RTAioMgrFileRead(RTAIOMGRFILE hAioMgrFile, RTFOFF off, + PRTSGBUF pSgBuf, size_t cbRead, void *pvUser); + +/** + * Initiate a write request to the given file handle. + * + * @returns IPRT status code. + * @param hAioMgrFile The file handle to write to. + * @param off Start offset to write to. + * @param pSgBuf S/G buffer to read from. The buffer is advanced + * by the amount of data to write. + * @param cbWrite Number of bytes to write. + * @param pvUser Opaque user data given in the completion callback. + */ +RTDECL(int) RTAioMgrFileWrite(RTAIOMGRFILE hAioMgrFile, RTFOFF off, + PRTSGBUF pSgBuf, size_t cbWrite, void *pvUser); + +/** + * Initiates a flush request for the given file handle. + * + * @returns IPRT statuse code. + * @param hAioMgrFile The file handle to write to. + * @param pvUser Opaque user data given in the completion callback. + */ +RTDECL(int) RTAioMgrFileFlush(RTAIOMGRFILE hAioMgrFile, void *pvUser); + +/** @} */ + +RT_C_DECLS_END + +#endif /* !IPRT_INCLUDED_aiomgr_h */ + |