class pipeline :object
..end
pipeline
object is a FIFO queue of HTTP calls. It is called
"pipeline" because it is processed asynchronously: Requests may be
sent to the HTTP server independently of whether responses of the
previous requests already arrived or not.
Furthermore, a pipeline
object may keep connections to several
servers at once. (More exactly, it has a FIFO queue for every
server it is connected with.)
The pipeline
object keeps track what is happening, so you need
not to care about the details of communications. The API is
simple: Create a pipeline
object, do some setup (add authentication
methods; configure the proxy to use), add the requests, and
run
the pipeline. The rest is done automatically. To get the results,
you can either memorize the requests you wanted to know yourself
and ask every request object about the reply of the server; or
you can specify that a callback function should be called once
the request is processed (with positive or negative result).
It is possible to add further requests to the pipeline from within
these callback functions.
If you want to have several pipelines, or some cooperation with
other network services, you may specify a Unixqueue.event_system
.
For example, to have two pipelines working concurrently:
let ues = Unixqueue.create_unix_event_system() in
let p1 = new pipeline in
let p2 = new pipeline in
p1 # set_event_system ues;
p2 # set_event_system ues;
Unixqueue.run ues (* run p1 and p2 in parallel *)
This works not only with pipelines, but with every network client
or server which is compatible with the Unixqueue
design.
method event_system : Unixqueue.event_system
method set_event_system : Unixqueue.event_system -> unit
method connection_cache : connection_cache
method set_connection_cache : connection_cache -> unit
method add_auth_handler : auth_handler -> unit
method set_proxy : string -> int -> unit
set_proxy name port
:
sets that an HTTP proxy name
listening on port
is to be usedmethod set_proxy_auth : insecure:bool -> string -> string -> unit
insecure
flag is set). Any realm is acceptable.method avoid_proxy_for : string list -> unit
"localhost"; ".our.net"
method set_proxy_from_environment : insecure:bool -> unit -> unit
http_proxy
and no_proxy
and set the proxy options from them. If insecure
is set,
basic authentication is enabled (otherwise only secure auth
methods like Digest).method set_socks5_proxy : string -> int -> unit
avoid_proxy_for
setting is
honoured.method configure_transport : transport_layer_id ->
transport_channel_type -> unit
configure_transport id transport
: Configures that messages with
transport layer ID id
are exchanged on transport
.
By default, there is only a configuration for
Nethttp_client.http_trans_id
, i.e. for normal unencrypted channels.
method set_tls_cache : tls_cache -> unit
null_tls_cache
)method set_transport_proxy : transport_layer_id ->
string ->
int -> (string * string * bool) option -> proxy_type -> unit
set_transport_proxy id host port auth ptype
: Sets a special
proxy for the transport identified by id
. This overrides
set_proxy
, set_proxy_auth
, and set_socks5_proxy
for the
given transport.
The auth
triple contains (user,password,insecure)
.
method set_transport_proxy_from_environment : insecure:bool -> (string * transport_layer_id) list -> unit
set_proxy_from_environment
, this method inspects environment
variables and configures the proxy settings. This function, however,
is more flexible, and can use different environment variables for
different transports.
The argument list has pairs (var_name, id)
meaning that the
environment variable var_name
configures the proxy for id
.
For instance,
[("http_proxy", http_trans_id); ("https_proxy", https_trans_id)]
means that these two variables are used for the respective
transports.
The variable "no_proxy"
is interpreted anyway.
insecure
: whether basic authentication is enabled.
method reset : unit -> unit
No_reply
(i.e. you get the exception
No_reply
if you try to access the response).
If there are callbacks for these requests, the callback
functions are invoked.
The queues of open requests and replies are cleared. All
connections to all servers are inactivated.
Inactivation means that open connections are given back
to the connection cache for further reuse if the state
of the connection allows this; otherwise the connections are
closed.
method add : http_call -> unit
method add_with_callback : http_call -> (http_call -> unit) -> unit
After the call has been processed, the callback function
is called. This function is called for every call that
leaves the pipeline, it does not matter whether processing
was successful or not. Invoke status
on the message
to get what happened; either some status information from the
server is available (perhaps OK status), or an exception is
indicated.
method add_e : http_call -> http_call Uq_engines.engine
c
is added to the pipeline, and
when it is processed, the returned engine transitions to the
state `Done c
.method proxy_type : string -> proxy_type option
proxy_type url
returns Some pt
if a proxy would be used for this
url
, and None
if a direct connection would be made.method proxy_type_of_call : http_call -> proxy_type option
method transport_layer : http_call -> transport_layer_id
method run : unit -> unit
http_call
object and will be raised once the state of the object is
queried.
Under certain conditions (serious network errors) run
does
not catch the exception; it simply cleans its own state up
(aborting the errorneous network connection). In this case,
simply invoke run
again to continue.
run
terminates normally if the pipeline becomes empty.
The engine handles the following HTTP return codes itself:
method get_options : http_options
method set_options : http_options -> unit
method number_of_open_messages : int
method number_of_open_connections : int
method connections : (string * int * int) list
(host, port, queue_length)
method cnt_new_connections : int
method cnt_timed_out_connections : int
method cnt_crashed_connections : int
method cnt_server_eof_connections : int
method cnt_successful_connections : int
method cnt_failed_connections : int
method reset_counters : unit -> unit
cnt_new_connections
: Is increased when a new connection attempt
is started (that may fail or timeout in the future). Reconnects
do not count.cnt_timed_out_connections
: Is increased whenever an established
connection times out. Usually, it is immediately reconnected.cnt_crashed_connections
: Is increased whenever an established
connection crashes. Usually, it is immediately reconnected.cnt_failed_connections
: Is increased when a timed out or
crashed connection exceeds the maximum number of errors, and it is
not tried to reconnect.cnt_successful_connections
: Is increased when all HTTP calls
have been replied.
cnt_new_connections = cnt_failed_connections + cnt_successful_connections