1#ifndef BASE_AIO_H
2#define BASE_AIO_H
3
4#include "types.h"
5
6/**
7 * Wraps a @link IOHANDLE @endlink for asynchronous writing.
8 *
9 * @ingroup File-IO
10 *
11 * @param io Handle to the file.
12 *
13 * @return The handle for asynchronous writing.
14 */
15ASYNCIO *aio_new(IOHANDLE io);
16
17/**
18 * Locks the `ASYNCIO` structure so it can't be written into by
19 * other threads.
20 *
21 * @ingroup File-IO
22 *
23 * @param aio Handle to the file.
24 */
25void aio_lock(ASYNCIO *aio);
26
27/**
28 * Unlocks the `ASYNCIO` structure after finishing the contiguous
29 * write.
30 *
31 * @ingroup File-IO
32 *
33 * @param aio Handle to the file.
34 */
35void aio_unlock(ASYNCIO *aio);
36
37/**
38 * Queues a chunk of data for writing.
39 *
40 * @ingroup File-IO
41 *
42 * @param aio Handle to the file.
43 * @param buffer Pointer to the data that should be written.
44 * @param size Number of bytes to write.
45 */
46void aio_write(ASYNCIO *aio, const void *buffer, unsigned size);
47
48/**
49 * Queues a newline for writing.
50 *
51 * @ingroup File-IO
52 *
53 * @param aio Handle to the file.
54 */
55void aio_write_newline(ASYNCIO *aio);
56
57/**
58 * Queues a chunk of data for writing. The `ASYNCIO` struct must be
59 * locked using @link aio_lock @endlink first.
60 *
61 * @ingroup File-IO
62 *
63 * @param aio Handle to the file.
64 * @param buffer Pointer to the data that should be written.
65 * @param size Number of bytes to write.
66 */
67void aio_write_unlocked(ASYNCIO *aio, const void *buffer, unsigned size);
68
69/**
70 * Queues a newline for writing. The `ASYNCIO` struct must be locked
71 * using @link aio_lock @endlink first.
72 *
73 * @ingroup File-IO
74 *
75 * @param aio Handle to the file.
76 */
77void aio_write_newline_unlocked(ASYNCIO *aio);
78
79/**
80 * Checks whether errors have occurred during the asynchronous writing.
81 *
82 * Call this function regularly to see if there are errors. Call this
83 * function after @link aio_wait @endlink to see if the process of writing
84 * to the file succeeded.
85 *
86 * @ingroup File-IO
87 *
88 * @param aio Handle to the file.
89 *
90 * @return `0` on success, or non-`0` on error.
91 */
92int aio_error(ASYNCIO *aio);
93
94/**
95 * Queues file closing.
96 *
97 * @ingroup File-IO
98 *
99 * @param aio Handle to the file.
100 */
101void aio_close(ASYNCIO *aio);
102
103/**
104 * Wait for the asynchronous operations to complete.
105 *
106 * @ingroup File-IO
107 *
108 * @param aio Handle to the file.
109 */
110void aio_wait(ASYNCIO *aio);
111
112/**
113 * Frees the resources associated with the asynchronous file handle.
114 *
115 * @ingroup File-IO
116 *
117 * @param aio Handle to the file.
118 */
119void aio_free(ASYNCIO *aio);
120
121#endif
122