Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 204 lines (151 sloc) 7.922 kb
fccc685 Initial open-source release
MLstate authored
1 (*
2 Copyright © 2011 MLstate
3
4 This file is part of OPA.
5
6 OPA is free software: you can redistribute it and/or modify it under the
7 terms of the GNU Affero General Public License, version 3, as published by
8 the Free Software Foundation.
9
10 OPA is distributed in the hope that it will be useful, but WITHOUT ANY
11 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
12 FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for
13 more details.
14
15 You should have received a copy of the GNU Affero General Public License
16 along with OPA. If not, see <http://www.gnu.org/licenses/>.
17 *)
18
19 (**
20 Bindings with Epoll
21
22 @see "http://linux.die.net/man/2/epoll_ctl" or man pages of epoll
23 @see "binding_epoll.c" for the c-implementation of external values
24 @author Laurent Le Brun
25 @author Cedric Soulas
26 @author Mathieu Barbin (documentation and masking implementation with abstract types)
27 *)
28
29 (** {6 Error reporting} *)
30
31 (**
32 Error management is complex dealing with a C binding because there is no exception in C.
33 However, the C libraries often provides a function to get the last code of error (or directly
34 accessing the [errno] variable), and a function to get a printable message from its code.
35
36 We export these functions in this interface as deprecated functions, because they are potentially
37 still used in existing code.
38
39 But in ocaml, we prefer having an exception with the error message in the exception
40 it self, using a exception constructor.
41
42 In the implementation of functions of this module calling C functions,
43 we check every returned code, and if an error occurs, we raise the exception [Error]
44 with the current error code and its corresponding message.
45 *)
46
47 (** The abstract type of an error *)
48 type error
49
50 (** Get the C code corresponding to the error *)
51 val error_code : error -> int
52
53 (** Get a printable message corresponding to the error *)
54 val error_message : error -> string
55
56 (** The exception raised in case of error. Functions of this module which possibly raise this exceptions are taged *)
57 exception Error of error
58
59 (** Low-level : Return a printable message corresponding to the last error.
60 @deprecated Please do not use it in new code *)
61 val last_error_message : unit -> string
62
63 (** Low-level : Get an int corresponding to the type of the last error.
64 meaning of values : see c documentation of epoll
65 @deprecated Please do not use it in new code *)
66 val last_error_code : unit -> int
67
68 (** {6 Epoll private descriptors} *)
69
70 (**
71 An epoll descriptors is a structure for making epoll requests, related to [Unix.file_descr]
72 *)
73
74 (** The abstract type of epoll file descriptors *)
75 type epoll_descriptor
76
77 (**
78 Open an epoll descriptor by requesting the kernel to allocate an event backing
79 store dimensioned for [size] descriptors.
80
81 The size is not the maximum size of the backing store but just a {b hint} to the kernel
82 about how to dimension internal structures.
83
84 The returned file descriptor will be used for all the subsequent calls to the epoll interface.
85
86 The file descriptor returned by [create] must be closed by using [close].
87
88 @raise Error if the c call failed.
89 *)
90 val create : int -> epoll_descriptor
91
92 (** Closing a [epoll_descriptor] previously created with [create]
93 {b THIS FUNCTION IS YET IMPLEMENTED BUT NOT TESTED}
94 @raise Error if the c call failed *)
95 val close : epoll_descriptor -> unit
96
97 (** {6 Epoll events} *)
98
99 (**
100 Events are used to tell what kind of conditions should be waited by Epoll. (read access, write access, etc...)
101
102 Events are represented by C-flags in C, and can be combined with a {b lor}.
103 For more control about events to be passed to the C functions, the type events is abstract.
104
105 Events are documented there : http://linux.die.net/man/2/epoll_ctl
106
107 They are C MACRO, like {b EPOLLIN}, {b EPOLLOUT} and their value cannot be determined
108 staticaly (too dangerous). So the events flags are build in C using the macro, and returned
109 to caml, available as a value of the abstract type [events].
110
111 Currently only 4 events are published in this interface. If you need more, please
112 update the implementation carrefully.
113
114 The interface events which are currently used, a function
115 to combine them, and functions to know, given a combined events if a event is part of it.
116 *)
117
118 (** The abstract types of epoll events *)
119 type event_mask
120 type supported_event = In | Out | Hup | Err | Unsupported of event_mask
121 type event
122 val combine : event list -> event_mask
123
124 (** This event is used if you want to discard every other events (using [Epoll.modif]) but
125 if you does not want to disard the [file_descr] from the [fd] handled by the [epoll_descriptor] *)
126 (* It should be forbiden *)
127 (* val event_empty : events *)
128
129 val event_mask_to_list : event_mask -> supported_event list
130
131
132 (** {6 Epoll requests} *)
133
134 (**
135 Functions [add], [del], [modif] are based on the function [epoll_ctl(2)] of the epoll library.
136
137 Theses functions control an [epoll_descriptor], by requesting that the corresponding operations
138 (add, modif, del) be performed on the target [Unix.file_descr].
139
140 The [events] describes the kind of events which should be catched by epoll, occuring to the [Unix.file_descr].
141
142 Hack : weblib is also used with [dummy_connection] which are recognized by the fact that the associated
143 [Unix.file_descr] has a negative value. In this case, the functions [add], [del] and [modif] ignore their
144 arguments (nothin is done, not any c-call).
145
146 @see "http://linux.die.net/man/2/epoll_ctl" for the documentation of [epoll_ctl(2)]
147 *)
148
149 (** Tell an [epoll_descriptor] that it {b should no more handle} any events occuring to a [Unix.file_descr].
150 This call remove the [file_descr] from the descr handled by the [epoll_descriptor].
151 It means that both In an Out filters are removed
152 Error cases may be related to the following problems :
153 + [fd] is not handled by [epoll_descriptor].
154 + [fd] is not a valid file descriptor, etc...
155 @raise Error if the c call failed. *)
156 val del : epoll_descriptor -> Unix.file_descr -> unit
157
158 (**
159 Tell an [epoll_descriptor] to listen both In and Out events ono a [Unix.file_descr]
160 By default, it assumes that the file descriptor has already been registered
161 *)
162 val listen_in_out : epoll_descriptor -> ?is_new_fd:bool -> Unix.file_descr -> unit
163
164 (**
165 Tell an [epoll_descriptor] to listen only In event on a [Unix.file_descr]
166 If the Out event was filtered, I will now be ignored
167 *)
168 val listen_in_only : epoll_descriptor -> bool -> Unix.file_descr -> unit
169
170 (**
171 Tell an [epoll_descriptor] to listen only Out event on a [Unix.file_descr]
172 If the In event was filtered, I will now be ignored
173 *)
174 val listen_out_only : epoll_descriptor -> bool -> Unix.file_descr -> unit
175
176 (**
177 [wait ?tout epd maxevents ]
178 Wait for events handled by the epoll descriptor [epd] for a maximum time of [tout] milliseconds.
179 The returned array will contain the events that will be available for the caller.
180 Up to [maxevents] are returned by wait. The maxevents parameter must be greater than zero.
181
182 Specifying a timeout of [-1] makes [epoll_wait(2)] wait indefinitely,
183 while specifying a timeout equal to [0] makes [epoll_wait(2)] to return immediately even
184 if no events are available.
185 *)
186 val wait : ?tout:int -> epoll_descriptor -> int -> (Unix.file_descr * supported_event list) array
187
188 (** {6 Debug} *)
189
190 (**
191 For printing [epoll_descriptors], [events], or [Unix.file_descr], we provide functions
192 to access the int hidden by the implementation.
193 Do not use it in standard code, only for unit tests
194 *)
195 module Debug :
196 sig
197 val int_of_filedescr : Unix.file_descr -> int
198 val filedescr_of_int : int -> Unix.file_descr
199 val int_of_events : event_mask -> int
200 val int_of_epoll_descriptor : epoll_descriptor -> int
201 (* val test : unit -> unit *)
202 end
203
Something went wrong with that request. Please try again.