1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
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 */
|
