← Back to branch summary

~ubuntu-branches/ubuntu/trusty/ocamlnet/trusty

« back to all changes in this revision

Viewing changes to src/netstring/netchannels.mli

  • Committer: Bazaar Package Importer
  • Author(s): Stéphane Glondu
  • Date: 2011-09-02 14:12:33 UTC
  • mfrom: (18.2.3 sid)
  • Revision ID: james.westby@ubuntu.com-20110902141233-zbj0ygxb92u6gy4z
Tags: 3.4-1
http://bugs.debian.org/637147
* New upstream release
  - add a new NetcgiRequire directive to ease dependency management
    (Closes: #637147)
  - remove patches that were applied upstream:
    + Added-missing-shebang-lines-in-example-shell-scripts
    + Try-also-ocamlc-for-POSIX-threads

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/netstring/netchannels.mli
1
 
(* $Id: netchannels.mli 1009 2006-10-01 20:26:01Z gerd $
 
1
(* $Id: netchannels.mli 1613 2011-06-08 15:45:17Z gerd $
2
2
 * ----------------------------------------------------------------------
3
3
 *
4
4
 *)
59
59
 * process data, but is in non-blocking mode, both methods now return the
60
60
 * value 0. In previous releases of ocamlnet, the behaviour was not
61
61
 * defined.
 
62
 *
 
63
 * {b Ocamlnet-3.0} changed the behavior of [close_out]. Errors are no longer
 
64
 * reported - instead, the exception is logged to {!Netlog}. For a stricter
 
65
 * error handling, it is suggested to call [flush] first. Also, [close_in]
 
66
 * and [close_out] no longer raise [Closed_channel] when the channel is
 
67
 * already closed. Read more about this in the section
 
68
 * {!Netchannels.rec_out_channel.close_error}.
62
69
 *)
63
70
 
64
71
exception Closed_channel
110
117
  method close_in : unit -> unit
111
118
    (** Closes the channel for input.
112
119
     *
113
 
     * When the channel is already closed, the exception [Closed_channel] will
114
 
     * be raised if an ocamlnet implementation is used. For implementations
115
 
     * of other libraries there is no standard for this case.
 
120
     * When the channel is already closed, this is a no-op.
 
121
     *
 
122
     * Error policy: Exceptions are only raised in cases of serious
 
123
     * corruption, e.g. if the underlying descriptor is invalid.
116
124
     *)
117
125
end
118
126
 
160
168
     *)
161
169
  method flush : unit -> unit
162
170
    (** If there is a write buffer, it will be flushed. Otherwise, nothing
163
 
     * happens
 
171
     * happens.
164
172
     *)
165
173
  method close_out : unit -> unit
166
174
    (** Flushes the buffer, if any, and closes the channel for output.
167
175
     *
168
 
     * When the channel is already closed, the exception [Closed_channel] will
169
 
     * be raised if an ocamlnet implementation is used. For implementations
170
 
     * of other libraries there is no standard for this case.
 
176
     * When the channel is already closed, this is a no-op.
171
177
     *)
 
178
 
 
179
 (** {2:close_error How to close channels in case of errors}
 
180
 
 
181
     The [close_out] method has actually two tasks: First, it writes out
 
182
     all remaining data (like [flush]), and second, it releases OS
 
183
     resources (e.g. closes file descriptors). There is the question
 
184
     what has to happen when the write part fails - is the resource released
 
185
     anyway or not?
 
186
 
 
187
     We choose here a pragmatic approach under the assumption that
 
188
     an OS error at close time is usually unrecoverable, and it is
 
189
     more important to release the OS resource. Also, we
 
190
     assume that the user is wise enough to call [flush] first if
 
191
     it is essential to know write errors at close time. Under these
 
192
     assumptions:
 
193
 
 
194
     - The [flush] method fully reports any errors when writing out
 
195
       the remaining data.
 
196
     - When [flush] raises an error exception, it should discard
 
197
       any data in the buffer. This is not obligatory, however,
 
198
       but considered good practice, and is subject to discussion.
 
199
     - The [close_out] method usually does not report errors by
 
200
       raising exceptions, but only by logging them via {!Netlog}.
 
201
       The OS resource is released in any case. As before, this
 
202
       behavior is not obligatory, but considered as good practice,
 
203
       and subject to discussion.
 
204
 
 
205
     This ensures that the following code snippet reports all errors, but also
 
206
     releases OS resources:
 
207
     
 
208
     {[
 
209
       try 
 
210
         ch # flush();
 
211
         ch # close_out();
 
212
       with error -> 
 
213
          ch # close_out(); raise error
 
214
     ]}
 
215
 
 
216
     There are some cases where data can be first written when it is
 
217
     known that the channel is closed. These data would not be written
 
218
     by a preceding [flush]. In such cases:
 
219
 
 
220
     - The best way to deal with it is to define another method,
 
221
       e.g. called [write_eof], that marks the data as logically 
 
222
       being complete, so a following [flush] can do the complete
 
223
       shutdown cycle of the channel.
 
224
     - At least, however, one should allow then that a double
 
225
       [close_out] releases the descriptor: the first [close_out]
 
226
       will report the error condition as exception, but discard
 
227
       all data in the channel. The second [close_out] finally
 
228
       releases the OS resource.
 
229
 
 
230
     In any way, hard errors indicating bugs of the program logic
 
231
     (like invalid file descriptors) should always be immediately
 
232
     reported.
 
233
  *)
172
234
end
173
235
 
174
236
(** Basic Unix-level class type for output channels as used by ocamlnet. In addition
309
371
(** {1:input Input channels} *)
310
372
 
311
373
class input_channel :
 
374
  ?onclose:(unit -> unit) ->
312
375
  in_channel ->
313
376
    in_obj_channel
314
377
  (** Creates an input channel from an [in_channel], which must be open.
318
381
   * non-seekable channels.
319
382
   *
320
383
   * The method [close_in] also closes the underlying [in_channel].
 
384
   *
 
385
   * The function [onclose] is called after the [in_channel] has been closed.
321
386
   *)
322
387
 
323
388
 
383
448
   * This function does not work for non-blocking channels.
384
449
   *)
385
450
 
 
451
val lines_of_in_obj_channel : in_obj_channel -> string list
 
452
  (** Reads from the input channel until EOF and returns the lines
 
453
   * as string list. The input channel is not closed.
 
454
   *
 
455
   * This function does not work for non-blocking channels.
 
456
   *)
 
457
 
386
458
val with_in_obj_channel : 
387
459
  (#in_obj_channel as 'a) -> ('a -> 'b) -> 'b
388
460
  (** [with_in_obj_channel ch f]:
406
478
   * non-seekable channels.
407
479
   *
408
480
   * The method [close_out] also closes the underlying [out_channel].
 
481
   * There is some implicit logic to either use [close_out] or [close_out_noerr]
 
482
   * depending on whether the immediately preceding operation already reported
 
483
   * an error.
409
484
   *
410
485
   * @param onclose this function is called when the [close_out] method is
411
486
   * invoked, just after the underlying [out_channel] has been closed.
423
498
   *
424
499
   * When [close_out] is invoked, the subprocess is [wait]ed for. If the
425
500
   * process exits with code 0, the method returns normally. Otherwise,
426
 
   * the exception [Command_failure] is raised.
 
501
   * the exception [Command_failure] is raised. (The channel is closed
 
502
   * even if this exception is raised.)
427
503
   *
428
504
   * @param onclose this function is called when the [close_out] method is
429
505
   * invoked, just after the underlying descriptor has been closed.
720
796
   *
721
797
   * The method [close_in] also closes the file descriptor.
722
798
   *
 
799
   * This class also supports Win32 proxy descriptors referring to an input
 
800
   * channel.
 
801
   *
723
802
   * @param blocking Whether the channel waits for data if it is not
724
803
   * possible to read from the (non-blocking) descriptor. Defaults to [true].
725
804
   * @param start_pos_in The position to which [pos_in] is initialized when
740
819
   *
741
820
   * The method [close_out] also closes the file descriptor.
742
821
   *
 
822
   * This class also supports Win32 proxy descriptors referring to an output
 
823
   * channel.
 
824
   *
743
825
   * @param blocking Whether the channel waits until it can output if it is not
744
826
   * possible to write to the (non-blocking) descriptor. Defaults to [true].
745
827
   * @param start_pos_out The position to which [pos_out] is initialized when
761
843
   *
762
844
   * The [pos_in] and [pos_out] methods returns logical positions.
763
845
   *
 
846
   * This class supports sockets and Win32 named pipes. Note, however,
 
847
   * that for Win32 named pipes it is not possible to shut down only one
 
848
   * direction of the bidirectional data channel.
 
849
   *
764
850
   * @param blocking See {!input_descr} and {!output_descr}
765
851
   * @param start_pos_in The position to which [pos_in] is initialized when
766
852
   * the channel is created, by default 0
796
882
   * the triple (name, inch, outch) containing the file [name],
797
883
   * the file opened as in_channel [inch] and as out_channel [outch].
798
884
   *
799
 
   * @param tmp_directory By default the current directory
800
 
   * @param tmp_prefix By default ["netstring"]. It is better to have a prefix
801
 
   *   that is likely to be unique, e.g. the process ID, or the current time.
 
885
   * @param tmp_directory Defaults to {!Netsys_tmp.tmp_directory()}
 
886
   * @param tmp_prefix By default ["netstring"]. This needs not to be
 
887
   *   unique, but just descriptive.
802
888
   * @param mode The creation mask of the file; defaults to 0o600, i.e. the
803
889
   *   file is private for the current user
804
890
   * @param limit Limits the number of trials to find the unique suffix.
833
919
 
834
920
class pipe :
835
921
  ?conv:(Netbuffer.t -> bool -> Netbuffer.t -> unit) ->
 
922
  ?buffer_size:int -> 
836
923
  unit ->
837
924
    io_obj_channel
838
925
  (** A [pipe] has two internal buffers (realized by Netbuffer). The