Search documentation of jhn_stdlib

# jhn_server behaviour (jhn_stdlib v5.10.3)

View Source

This is a generic server in the spirit of OTP's gen_server but subtly different. The behaviour module provides the server of a client-server relation. A generic server process (jhn_server) implemented using this module has a standard set of interface functions. It also fits into an OTP supervision tree and supports generic OTP tooling for, e.g., dynamic upgrades.

A jhn_server process assumes all specific parts to be located in a callback module exporting a predefined set of functions, some optional.

The relationship between the behavior functions and the callback functions is as follows: ----->/-----> fuction call/return ====> message sent

User module: <-------------> jhn_server module: <--/==> Callback module:

-----------------------------------------------------------------------

jhn_server:create/1/2 -----> proc_lib:spawn ----> init/1

jhn_server:create/1/2 <----- proc_lib:spawn <==== init/1

-----------------------------------------------------------------------

jhn_server:call/2/3 =====> (jhn_server) -----> request/2

jhn_server:call/2/3 <===== (jhn_server) <----- jhn_server:reply/1/2 (optional)

-----------------------------------------------------------------------

jhn_server:sync/1/2 =====> (jhn_server)

jhn_server:sync/1/2 <===== (jhn_server)

-----------------------------------------------------------------------

jhn_server:cast/2/3 =====> (jhn_server) -----> request/2

All the following are optional

Other process =====> Callback module

-----------------------------------------------------------------------

Id ! Message =====> message/2

sys:terminate/2 =====> terminate/3

sys:code_change/4 =====> code_change/3

sys:get_status/2 =====> format_status/2

If a callback function fails or returns a bad value, the jhn_server process terminates. N.B. that a jhn_server process does not trap exit signals automatically, this must be explicitly initiated in the callback module. The process is by default linked to the parent.

jhn_server supports hibernation. Any call, cast or plain message sent to the process that does not have matching clause in the appropriate request/2 or messsage/2 call back function will be discarded and logged as unexpected. If the optional callback funtion message/2 is not defined there are no matching function clauses at all.

The callback module shall export:

init(Args) ==> {ok, State} | {hibernate, State} | ignore | {error, stop} | {stop, Reason}

request(Msg, State) ==> {ok, State} | {hibernate, State} | {stop, Reason}

The callback module can export:

message(Msg, State) ==> {ok, State} | {hibernate, State} | {stop, Reason}

terminate(Reason, State) ==> Return value ignored

Lets the user module clean up always called when server terminates

code_change(OldVsn, Data, Extra) ==> {ok, State}

format_status(Opt, _) ==> {ok, State}

Uses the old format will be replaced.

# Summary

## Types

from/0
init_return/1
opt/0
opts/0
return/1
server_ref/0

## Callbacks

code_change/3
format_status/2
init/1
message/2
request/2
terminate/3

## Functions

abcast(Name, Msg)

A cast is made to servers registered as Server on all the connected nodes.

abcast(Nodes, Name, Msg)

A cast is made to servers registered as Server on all Nodes.

call(Server, Msg)

A call is made to Server with default timeout 5000ms.

call(Server, Msg, Timeout)

A call is made to Server with Timeout. Will generate a timeout exception if the Server takes more than Timeout time to answer. Generates an exception if the process is dead, dies, or no process registered under that name. If the server replies that is returned from the call.

cancel(Ref)

A timer a timer started using delayed_cast/2, returns time remaining or false.

cast(Server, Msg)

A cast is made to the server, allways returns ok.

create(Mod)

Creates a jhn_server.

create(Mod, Options)

Creates a jhn_server with options. Options are: {link, Boolean} -> if the server is linked to the parent, default true {timeout, infinity | Integer} -> Time in ms for the server to create and initialise, after that an exception is generated, default 5000. {name, Atom} -> name that the server is registered under. {arg, Term} -> argument provided to the init/1 callback function, default is 'no_arg'.

delayed_cast(Time, Msg)

A cast is made to the calling Server after Delay ms, always returns a timer reference that can be canceled using cancel/1.

from()

Called inside a request/2 of callback function for a call it will provide an opaque data data enables a reply to the call outside the scope of the callback function.

reply(Msg)

Called inside callback function to provide reply to a call.

reply(From, Msg)

Called by any process will send a reply to the one that sent the request to the server, the From argument is the result from a call to from/1 inside a request/2 callback function in response to a jhn_server:call/2/3

sync(Server)

A synchronization is made with Server with default timeout 5000ms.

sync(Server, Timeout)

A synchronization is made with Server with Timeout. Will generate a timeout exception if the Server takes more than Timeout time to answer. Generates an exception if the process is dead, dies, or no process registered under that name. If the server returns, ok is returned.

type()

Called inside a request/2 and it tells if it is a call or a cast.

# Types

# from/0

    -type from() :: reference().

# init_return/1

    -type init_return(State) :: ignore | return(State).

# opt/0

    -type opt() :: {link, boolean()} | {timeout, infinity | non_neg_integer()} | {name, atom()} | {arg, _}.

# opts/0

    -type opts() :: [opt()].

# return/1

    -type return(State) :: {ok, State} | {hibernate, State} | {error, _} | {stop, _}.

# server_ref/0

    -type server_ref() :: atom() | {atom(), node()} | pid().

# Callbacks

# code_change/3

(optional)

    -callback code_change(_, State, _) -> return(State).

# format_status/2

(optional)

    -callback format_status(_, _) -> _.

# init/1

    -callback init(State) -> init_return(State).

# message/2

(optional)

    -callback message(_, State) -> return(State).

# request/2

    -callback request(_, State) -> return(State).

# terminate/3

(optional)

    -callback terminate(_, _, _) -> _.

# Functions

# abcast(Name, Msg)

    -spec abcast(atom(), _) -> ok.

A cast is made to servers registered as Server on all the connected nodes.

# abcast(Nodes, Name, Msg)

    -spec abcast([node()], atom(), _) -> ok.

A cast is made to servers registered as Server on all Nodes.

# call(Server, Msg)

    -spec call(server_ref(), _) -> _.

A call is made to Server with default timeout 5000ms.

# call(Server, Msg, Timeout)

    -spec call(server_ref(), _, timeout()) -> _.

A call is made to Server with Timeout. Will generate a timeout exception if the Server takes more than Timeout time to answer. Generates an exception if the process is dead, dies, or no process registered under that name. If the server replies that is returned from the call.

# cancel(Ref)

    -spec cancel(reference()) -> non_neg_integer() | false.

A timer a timer started using delayed_cast/2, returns time remaining or false.

# cast(Server, Msg)

    -spec cast(server_ref(), _) -> ok.

A cast is made to the server, allways returns ok.

# create(Mod)

    -spec create(atom()) -> {ok, pid()} | ignore | {error, _}.

Creates a jhn_server.

# create(Mod, Options)

    -spec create(atom(), opts()) -> {ok, pid()} | ignore | {error, _}.

Creates a jhn_server with options. Options are: {link, Boolean} -> if the server is linked to the parent, default true {timeout, infinity | Integer} -> Time in ms for the server to create and initialise, after that an exception is generated, default 5000. {name, Atom} -> name that the server is registered under. {arg, Term} -> argument provided to the init/1 callback function, default is 'no_arg'.

# delayed_cast(Time, Msg)

    -spec delayed_cast(non_neg_integer(), _) -> reference().

A cast is made to the calling Server after Delay ms, always returns a timer reference that can be canceled using cancel/1.

# from()

    -spec from() -> from().

Called inside a request/2 of callback function for a call it will provide an opaque data data enables a reply to the call outside the scope of the callback function.

# reply(Msg)

    -spec reply(_) -> ok.

Called inside callback function to provide reply to a call.

# reply(From, Msg)

    -spec reply(from(), _) -> ok.

Called by any process will send a reply to the one that sent the request to the server, the From argument is the result from a call to from/1 inside a request/2 callback function in response to a jhn_server:call/2/3

# sync(Server)

    -spec sync(server_ref()) -> ok.

A synchronization is made with Server with default timeout 5000ms.

# sync(Server, Timeout)

    -spec sync(server_ref(), timeout()) -> _.

A synchronization is made with Server with Timeout. Will generate a timeout exception if the Server takes more than Timeout time to answer. Generates an exception if the process is dead, dies, or no process registered under that name. If the server returns, ok is returned.

# type()

    -spec type() -> call | cast.

Called inside a request/2 and it tells if it is a call or a cast.