debuggers.hg

view tools/libaio/man/aio_suspend.3 @ 0:7d21f7218375

Exact replica of unstable on 051908 + README-this
author Mukesh Rathor
date Mon May 19 15:34:57 2008 -0700 (2008-05-19)
parents
children
line source
1 .TH aio_suspend 3 2002-09-12 "Linux 2.4" Linux AIO"
2 .SH NAME
3 aio_suspend \- Wait until one or more requests of a specific set terminates.
4 .SH SYNOPSYS
5 .nf
6 .B "#include <errno.h>"
7 .sp
8 .br
9 .B "#include <aio.h>"
10 .sp
11 .br
12 .BI "int aio_suspend (const struct aiocb *const list[], int nent, const struct timespec *timeout)"
13 .fi
14 .SH DESCRIPTION
15 Another method of synchronization is to wait until one or more requests of a
16 specific set terminated. This could be achieved by the
17 .IR "aio_*"
18 functions to notify the initiating process about the termination but in
19 some situations this is not the ideal solution. In a program which
20 constantly updates clients somehow connected to the server it is not
21 always the best solution to go round robin since some connections might
22 be slow. On the other hand letting the
23 .IR "aio_*"
24 function notify the
25 caller might also be not the best solution since whenever the process
26 works on preparing data for on client it makes no sense to be
27 interrupted by a notification since the new client will not be handled
28 before the current client is served. For situations like this
29 .IR "aio_suspend"
30 should be used.
31 .PP
32 When calling this function, the calling thread is suspended until at
33 least one of the requests pointed to by the
34 .IR "nent"
35 elements of the
36 array
37 .IR "list"
38 has completed. If any of the requests has already
39 completed at the time
40 .IR "aio_suspend"
41 is called, the function returns
42 immediately. Whether a request has terminated or not is determined by
43 comparing the error status of the request with
44 .IR "EINPROGRESS"
45 . If
46 an element of
47 .IR "list"
48 is
49 .IR "NULL"
50 , the entry is simply ignored.
52 If no request has finished, the calling process is suspended. If
53 .IR "timeout"
54 is
55 .IR "NULL"
56 , the process is not woken until a request
57 has finished. If
58 .IR "timeout"
59 is not
60 .IR "NULL"
61 , the process remains
62 suspended at least as long as specified in
63 .IR "timeout"
64 . In this case,
65 .IR "aio_suspend"
66 returns with an error.
67 .PP
68 When the sources are compiled with
69 .IR "_FILE_OFFSET_BITS == 64"
70 this
71 function is in fact
72 .IR "aio_suspend64"
73 since the LFS interface
74 transparently replaces the normal implementation.
75 .SH "RETURN VALUES"
76 The return value of the function is
77 .IR 0
78 if one or more requests
79 from the
80 .IR "list"
81 have terminated. Otherwise the function returns
82 .IR -1
83 and
84 .IR "errno"
85 is set.
86 .SH ERRORS
87 .TP
88 .B EAGAIN
89 None of the requests from the
90 .IR "list"
91 completed in the time specified
92 by
93 .IR "timeout"
94 .
95 .TP
96 .B EINTR
97 A signal interrupted the
98 .IR "aio_suspend"
99 function. This signal might
100 also be sent by the AIO implementation while signalling the termination
101 of one of the requests.
102 .TP
103 .B ENOSYS
104 The
105 .IR "aio_suspend"
106 function is not implemented.
107 .SH "SEE ALSO"
108 .BR aio(3),
109 .BR aio_cancel(3),
110 .BR aio_cancel64(3),
111 .BR aio_error(3),
112 .BR aio_error64(3),
113 .BR aio_fsync(3),
114 .BR aio_fsync64(3),
115 .BR aio_init(3),
116 .BR aio_read(3),
117 .BR aio_read64(3),
118 .BR aio_return(3),
119 .BR aio_return64(3),
120 .BR aio_suspend64(3),
121 .BR aio_write(3),
122 .BR aio_write64(3),
123 .BR errno(3),