.TH "Eliom_comet.Channel" 3o 2014-07-10 OCamldoc ""
.SH NAME
Eliom_comet.Channel \- Basic primitives needed for server push.
.SH Module
Module   Eliom_comet.Channel
.SH Documentation
.sp
Module
.BI "Channel"
 : 
.B sig  end

.sp
Basic primitives needed for server push\&.
.sp

.sp

.sp
.sp
.I type 
.B 'a
.I t 

.sp

.B v t
is the type of server\-to\-client communication channels
transporting data of type 
.B v

.sp

.sp
.I type comet_scope 
= 
.B [ `Client_process of Eliom_common.scope_hierarchy | `Site ]

.sp

.sp

.I val create 
: 
.B ?scope:[< comet_scope ] ->
.B   ?name:string -> ?size:int -> 'a Lwt_stream.t -> 'a t
.sp

.B create s
returns a channel sending the values returned by stream 
.B s
\&.
.sp
There are two kinds of channels created depending on the given
scope (defaults to 
.B Eliom_common\&.comet_client_process
)\&.
.sp
With scope 
.B Eliom_common\&.site_scope
all users knowing the name of
the channel can access it\&. Only one message queue is created: it
is what we call a //stateless// channel in the sense that the memory
used by the channel does not depend on the number of users\&.  The
channel can be reclaimed by the GC when there is no more reference to it\&.
The buffer channel has a limited buffer of size 
.B size
(default:
1000)\&. If the client requests too old messages, exception
.B Eliom_coment\&.Channel_full
will be raised (on client side)\&.
.sp
With a scope of level 
.B Eliom_common\&.client_process_scope
the
channel can only be accessed by the user who created it\&. It
can only be created when client process data is
available (that is: during a request)\&.
The eliom service created to communicate with the
client is only available in the scope of the client process\&. To
avoid memory leak when the client do not read sent data,
the channel has a limited 
.B size
\&. When a channel is full, no
data can be read from it anymore\&.
.sp
A channel can be used only once on client side\&. To be able
to receive the same data multiple times on client side, use
.B create (Lwt_stream\&.clone s)
every time\&.
.sp
To enforce the limit on the buffer size, the data is read into
.B stream
as soon as possible: If you want a channel that reads
data on the stream only when the client requests it, use
.B create_unlimited
instead, but be careful of memory leaks\&.
.sp

.sp

.I val create_unlimited 
: 
.B ?scope:Eliom_common.client_process_scope ->
.B   ?name:string -> 'a Lwt_stream.t -> 'a t
.sp

.B create_unlimited s
creates a channel which does not read
immediately on the stream\&. It is read only when the client
requests it: use it if the data you send depends on the time of
the request (for instance the number of unread mails)\&. Be
careful, the size of this stream is not limited: if the size of
the stream increases and your clients don\&'t read it, you may have
memory leaks\&.
.sp

.sp

.I val create_newest 
: 
.B ?name:string -> 'a Lwt_stream.t -> 'a t
.sp

.B create_newest s
is similar to 
.B create
.B       ~scope:Eliom_common\&.site_scope s
but only the last message is
returned to the client\&.
.sp

.sp

.I val external_channel 
: 
.B ?history:int ->
.B   ?newest:bool ->
.B   prefix:string -> name:string -> unit -> 'a t
.sp

.B external_channel ~prefix ~name ()
declares an external
channel\&. The channel was created by an instance of Eliom serving
the prefix 
.B prefix
(the prefix configured in the <site> tag of
the configuration file)\&. The channel was named by 
.B name
\&. Both
servers must run the exact same version of Eliom\&.
.sp
The optional 
.B newest
parameters tells whether the channel is a
new one\&. If the channel is not new, 
.B history
is the maximum
number of messages retrieved at the first request\&. The default
is 
.B 1
\&.
.sp

.sp

.I val wait_timeout 
: 
.B ?scope:Eliom_common.client_process_scope -> float -> unit Lwt.t
.sp

.B wait_timeout ~scope time
waits for a period of inactivity of
length 
.B time
in the 
.B scope
\&. Only activity on stateful
channels is taken into accounts\&.
.sp
The default 
.B scope
is 
.B Eliom_common\&.comet_client_process
\&.
.sp

.sp