.TH "Eliom_reference" 3o 2014-07-10 OCamldoc ""
.SH NAME
Eliom_reference \-  Server side state data, a.k.a Eliom references 
.SH Module
Module   Eliom_reference
.SH Documentation
.sp
Module
.BI "Eliom_reference"
 : 
.B sig  end

.sp

.B Server side state data, a\&.k\&.a Eliom references

.sp

.sp

.sp
.sp

.PP

.B === Please read the
.B     {% <<a_manual chapter="server\-state" | Eliom manual >> %}
.B     before this page to learn how server side state works\&.  ===

.PP
.I type 
.B ('a, +'storage)
.I eref' 

.sp
Eliom references come in two flavors: they may be stored persistently or
the may be volatile\&.  The module 
.B Volatile
allows creation of
references which can be, get, set, modify, and unset volatile references
through non\-Lwt functions\&.
.sp

.sp
.I type 
.B 'a
.I eref 
= 
.B ('a, [ `Persistent | `Volatile ]) eref'

.sp
The type of Eliom references whose content is of type 
.B \&'a
\&.
.sp

.sp

.I exception Eref_not_initialized 

.sp
Exception raised when trying to access an eref
that has not been initaliazed, when we don\&'t want to initialize it\&.
.sp

.sp

.I val eref 
: 
.B scope:[< Eliom_common.all_scope ] ->
.B   ?secure:bool -> ?persistent:string -> 'a -> 'a eref
.sp
The function 
.B eref ~scope value
creates an Eliom reference for
the given 
.B scope
and initialize it with 
.B value
\&. See the Eliom
manual for more information about \&.
.sp
Use the optional parameter 
.B ?persistent
if you want the data to
survive after relaunching the server\&. You must give an unique name
to the table in which it will be stored on the hard disk (using
Ocsipersist)\&.  Be very careful to use unique names, and to change
the name if you change the type of the data, otherwise the server
may crash (unsafe unmarshaling)\&. This parameter has no effect for
scope 
.B Eliom_common\&.request_scope
\&.
.sp
Use the optional parameter 
.B ~secure:true
if you want the data to
be available only using HTTPS\&. This parameter has no effect for
scopes 
.B Eliom_common\&.global_scope
, 
.B Eliom_common\&.site_scope
, and
.B Eliom_common\&.request_scope
\&.
.sp
Warning: Eliom references of scope 
.B Eliom_common\&.global_scope
,
.B Eliom_common\&.site_scope
or
.B Eliom_common\&.request_scope
may be created at any time ; but for other
scopes, they must be created when the site information is
available to Eliom, that is, either during the initialization
phase of the server (while reading the configuration file) or
during a request\&. Otherwise, it will raise the exception
.B Eliom_common\&.Eliom_site_information_not_available
\&. If you are
using static linking, you must delay the call to this function
until the configuration file is read, using
.B Eliom_service\&.register_eliom_module
\&. Otherwise you will also
get this exception\&.
.sp

.sp

.I val eref_from_fun 
: 
.B scope:[< Eliom_common.all_scope ] ->
.B   ?secure:bool -> ?persistent:string -> (unit -> 'a) -> 'a eref
.sp
The function 
.B eref_from_fun
works like the above 
.B Eliom_reference\&.eref
,
but instead of providing a value for the initial content, a function 
.B f
for
creating the initial content is provided (cf\&. also 
.B Lazy\&.lazy_from_fun
)\&.
.sp
In each scope, the function 
.B f
is called for creating the value of the
reference the first time the reference is read (by 
.B Eliom_reference\&.get
),
if the value has not been set explicitly before (by 
.B Eliom_reference\&.set
);
or if the reference was reset (by 
.B Eliom_reference\&.reset
) before\&.
.sp

.sp

.I val get 
: 
.B 'a eref -> 'a Lwt.t
.sp
The function 
.B get eref
returns the current value of the Eliom
reference 
.B eref
\&.
.sp
Warning: this function cannot be used outside of a service
handler when 
.B eref
has been created with a scope different of
.B Eliom_common\&.global_scope
; it can neither be used outside of an
Eliom module when 
.B eref
has been created with scope
.B Eliom_common\&.site_scope

.sp

.sp

.I val set 
: 
.B 'a eref -> 'a -> unit Lwt.t
.sp
The function 
.B set eref v
set 
.B v
as current value of the Eliom
reference 
.B eref
\&.
.sp
Warning: this function could not be used outside af a service
handler when 
.B eref
has been created with a scope different of
.B Eliom_common\&.global_scope
; it can neither be used outside of an
Eliom module when 
.B eref
has been created with scope
.B Eliom_common\&.site_scope

.sp

.sp

.I val modify 
: 
.B 'a eref -> ('a -> 'a) -> unit Lwt.t
.sp
The function 
.B modify eref f
modifies the content of the Eliom
reference 
.B eref
by applying the function 
.B f
on it\&.
.sp
Warning: this function could not be used outside af a service
handler when 
.B eref
has been created with a scope different of
.B Eliom_common\&.global_scope
; it can neither be used outside of an
Eliom module when 
.B eref
has been created with scope
.B Eliom_common\&.site_scope

.sp

.sp

.I val unset 
: 
.B 'a eref -> unit Lwt.t
.sp
The function 
.B unset eref
reset the content of the Eliom reference
.B eref
to its initial value\&.
.sp
Warning: this function could not be used outside af a service
handler when 
.B eref
has been created with a scope different of
.B Eliom_common\&.global_scope
; it can neither be used outside of an
Eliom module when 
.B eref
has been created with scope
.B Eliom_common\&.site_scope

.sp

.sp
.I module Volatile : 
.B sig  end

.sp
Same functions as in 
.B Eliom_reference
but a non\-Lwt interface
for non\-persistent Eliom references\&.
.sp

.sp
.I module Ext : 
.B sig  end

.sp

.sp