aiomgr.h revision 527eff46676ca64c098dc7d1bf0857408c3a6f82
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync/** @file
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * IPRT - Async I/O manager.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync/*
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * Copyright (C) 2013 Oracle Corporation
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync *
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * available from http://www.virtualbox.org. This file is free software;
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * you can redistribute it and/or modify it under the terms of the GNU
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * General Public License (GPL) as published by the Free Software
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync *
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * The contents of this file may alternatively be used under the terms
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * of the Common Development and Distribution License Version 1.0
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * VirtualBox OSE distribution, in which case the provisions of the
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * CDDL are applicable instead of those of the GPL.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync *
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * You may elect to license modified versions of this file under the
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * terms and conditions of either the GPL or the CDDL or both.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync#ifndef ___iprt_aiomgr_h
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync#define ___iprt_aiomgr_h
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync#include <iprt/cdefs.h>
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync#include <iprt/types.h>
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync#include <iprt/sg.h>
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync/**
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * Completion callback.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync *
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @returns nothing.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @param hAioMgrFile File handle the completed request was for.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @param rcReq Status code of the completed request.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @param pvUser Opaque user data given when the request was initiated.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsynctypedef DECLCALLBACK(void) FNRTAIOMGRREQCOMPLETE(RTAIOMGRFILE hAioMgrFile, int rcReq, void *pvUser);
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync/** Pointer to a completion callback. */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsynctypedef FNRTAIOMGRREQCOMPLETE *PFNRTAIOMGRREQCOMPLETE;
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsyncRT_C_DECLS_BEGIN
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync/**
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * Create a new async I/O manager.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync *
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @returns IPRT statuse code.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @param phAioMgr Where to store the new async I/O manager handle on success.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @param cReqsMax Maximum number of async I/O requests expected.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * Use UINT32_MAX to make it grow dynamically when required.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsyncRTDECL(int) RTAioMgrCreate(PRTAIOMGR phAioMgr, uint32_t cReqsMax);
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync/**
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * Retain a async I/O manager handle.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync *
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @returns New reference count on success, UINT32_MAX on failure.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @param hAioMgr The async I/O manager to retain.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsyncRTDECL(uint32_t) RTAioMgrRetain(RTAIOMGR hAioMgr);
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync/**
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * Releases a async I/O manager handle.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync *
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @returns New reference count on success (0 if closed), UINT32_MAX on failure.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * @param hAioMgr The async I/O manager to release.
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync */
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsyncRTDECL(uint32_t) RTAioMgrRelease(RTAIOMGR hAioMgr);
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync/**
3194da424708abdd288b28d96892b3a5f3f7df0bvboxsync * 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.
*
* @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,
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);
/**
* 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