1gen_server(3)              Erlang Module Definition              gen_server(3)
2
3
4

NAME

6       gen_server - Generic server behavior.
7

DESCRIPTION

9       This behavior module provides the server of a client-server relation. A
10       generic server process (gen_server) implemented using this module has a
11       standard  set  of  interface  functions  and includes functionality for
12       tracing and error reporting. It also fits into an OTP supervision tree.
13       For  more  information, see section  gen_server Behaviour in OTP Design
14       Principles.
15
16       A gen_server process assumes all specific parts  to  be  located  in  a
17       callback  module exporting a predefined set of functions. The relation‐
18       ship between the behavior functions and the callback  functions  is  as
19       follows:
20
21       gen_server module            Callback module
22       -----------------            ---------------
23       gen_server:start
24       gen_server:start_link -----> Module:init/1
25
26       gen_server:stop       -----> Module:terminate/2
27
28       gen_server:call
29       gen_server:multi_call -----> Module:handle_call/3
30
31       gen_server:cast
32       gen_server:abcast     -----> Module:handle_cast/2
33
34       -                     -----> Module:handle_info/2
35
36       -                     -----> Module:handle_continue/2
37
38       -                     -----> Module:terminate/2
39
40       -                     -----> Module:code_change/3
41
42       If  a  callback  function  fails or returns a bad value, the gen_server
43       process terminates.
44
45       A gen_server process handles system messages as  described  in  sys(3).
46       The sys module can be used for debugging a gen_server process.
47
48       Notice  that  a gen_server process does not trap exit signals automati‐
49       cally, this must be explicitly initiated in the callback module.
50
51       Unless otherwise stated, all functions in this module fail if the spec‐
52       ified  gen_server process does not exist or if bad arguments are speci‐
53       fied.
54
55       The gen_server process can go into hibernation (see erlang:hibernate/3)
56       if  a  callback  function  specifies  'hibernate' instead of a time-out
57       value. This can be useful if the server is expected to be  idle  for  a
58       long  time. However, use this feature with care, as hibernation implies
59       at least two garbage collections (when hibernating  and  shortly  after
60       waking  up)  and is not something you want to do between each call to a
61       busy server.
62
63       If the gen_server process needs to perform an action immediately  after
64       initialization  or  to  break the execution of a callback into multiple
65       steps, it can return {continue,Continue} in place of  the  time-out  or
66       hibernation  value, which will immediately invoke the handle_continue/2
67       callback.
68

EXPORTS

70       abcast(Name, Request) -> abcast
71       abcast(Nodes, Name, Request) -> abcast
72
73              Types:
74
75                 Nodes = [Node]
76                  Node = atom()
77                 Name = atom()
78                 Request = term()
79
80              Sends  an  asynchronous  request  to  the  gen_server  processes
81              locally  registered as Name at the specified nodes. The function
82              returns immediately and ignores nodes  that  do  not  exist,  or
83              where  the  gen_server  Name does not exist. The gen_server pro‐
84              cesses call Module:handle_cast/2 to handle the request.
85
86              For a description of the arguments, see multi_call/2,3,4.
87
88       call(ServerRef, Request) -> Reply
89       call(ServerRef, Request, Timeout) -> Reply
90
91              Types:
92
93                 ServerRef = Name | {Name,Node} | {global,GlobalName}
94                  | {via,Module,ViaName} | pid()
95                  Node = atom()
96                  GlobalName = ViaName = term()
97                 Request = term()
98                 Timeout = int()>0 | infinity
99                 Reply = term()
100
101              Makes a synchronous call to  the  ServerRef  of  the  gen_server
102              process  by  sending a request and waiting until a reply arrives
103              or a time-out occurs. The gen_server process  calls  Module:han‐
104              dle_call/3 to handle the request.
105
106              ServerRef can be any of the following:
107
108                * The pid
109
110                * Name, if the gen_server process is locally registered
111
112                * {Name,Node}, if the gen_server process is locally registered
113                  at another node
114
115                * {global,GlobalName}, if the gen_server process  is  globally
116                  registered
117
118                * {via,Module,ViaName},  if  the  gen_server process is regis‐
119                  tered through an alternative process registry
120
121              Request is any term that is passed as one of  the  arguments  to
122              Module:handle_call/3.
123
124              Timeout  is an integer greater than zero that specifies how many
125              milliseconds to wait for a reply, or the atom infinity  to  wait
126              indefinitely.  Defaults  to 5000. If no reply is received within
127              the specified time, the  function  call  fails.  If  the  caller
128              catches  the  failure  and  continues running, and the server is
129              just late with the reply, it can arrive at any time  later  into
130              the message queue of the caller. The caller must in this case be
131              prepared for this and discard any such garbage messages that are
132              two element tuples with a reference as the first element.
133
134              The  return  value  Reply is defined in the return value of Mod‐
135              ule:handle_call/3.
136
137              The call can fail for many reasons, including time-out  and  the
138              called gen_server process dying before or during the call.
139
140       cast(ServerRef, Request) -> ok
141
142              Types:
143
144                 ServerRef = Name | {Name,Node} | {global,GlobalName}
145                  | {via,Module,ViaName} | pid()
146                  Node = atom()
147                  GlobalName = ViaName = term()
148                 Request = term()
149
150              Sends an asynchronous request to the ServerRef of the gen_server
151              process and returns ok immediately, ignoring if the  destination
152              node  or  gen_server  process  does  not  exist.  The gen_server
153              process calls Module:handle_cast/2 to handle the request.
154
155              For a description of ServerRef, see call/2,3.
156
157              Request is any term that is passed as one of  the  arguments  to
158              Module:handle_cast/2.
159
160       enter_loop(Module, Options, State)
161       enter_loop(Module, Options, State, ServerName)
162       enter_loop(Module, Options, State, Timeout)
163       enter_loop(Module, Options, State, ServerName, Timeout)
164
165              Types:
166
167                 Module = atom()
168                 Options = [Option]
169                  Option = {debug,Dbgs} | {hibernate_after,HibernateAfterTime‐
170                 out}
171                  Dbgs = [Dbg]
172                  Dbg = trace | log | statistics
173                  | {log_to_file,FileName} | {install,{Func,FuncState}}
174                 State = term()
175                 ServerName = {local,Name} | {global,GlobalName}
176                  | {via,Module,ViaName}
177                  Name = atom()
178                  GlobalName = ViaName = term()
179                 Timeout = int() | infinity
180
181              Makes an existing process into a gen_server  process.  Does  not
182              return,  instead  the  calling  process  enters  the  gen_server
183              process receive loop  and  becomes  a  gen_server  process.  The
184              process  must have been started using one of the start functions
185              in proc_lib(3). The user is responsible for  any  initialization
186              of the process, including registering a name for it.
187
188              This  function is useful when a more complex initialization pro‐
189              cedure is needed than the gen_server process behavior provides.
190
191              Module, Options, and ServerName have the same meanings  as  when
192              calling  start[_link]/3,4.  However, if ServerName is specified,
193              the process must have been registered  accordingly  before  this
194              function is called.
195
196              State  and Timeout have the same meanings as in the return value
197              of Module:init/1. The callback module Module does  not  need  to
198              export an init/1 function.
199
200              The  function  fails if the calling process was not started by a
201              proc_lib start function, or if it is not registered according to
202              ServerName.
203
204       multi_call(Name, Request) -> Result
205       multi_call(Nodes, Name, Request) -> Result
206       multi_call(Nodes, Name, Request, Timeout) -> Result
207
208              Types:
209
210                 Nodes = [Node]
211                  Node = atom()
212                 Name = atom()
213                 Request = term()
214                 Timeout = int()>=0 | infinity
215                 Result = {Replies,BadNodes}
216                  Replies = [{Node,Reply}]
217                  Reply = term()
218                 BadNodes = [Node]
219
220              Makes  a  synchronous  call  to all gen_server processes locally
221              registered as Name at the specified nodes  by  first  sending  a
222              request  to  every  node  and  then  waits  for the replies. The
223              gen_server process  calls  Module:handle_call/3  to  handle  the
224              request.
225
226              The  function  returns a tuple {Replies,BadNodes}, where Replies
227              is a list of {Node,Reply} and BadNodes is a list  of  node  that
228              either did not exist, or where the gen_server Name did not exist
229              or did not reply.
230
231              Nodes is a list of node names to which  the  request  is  to  be
232              sent.   Default   value   is   the   list  of  all  known  nodes
233              [node()|nodes()].
234
235              Name is the locally registered name of each gen_server process.
236
237              Request is any term that is passed as one of  the  arguments  to
238              Module:handle_call/3.
239
240              Timeout  is an integer greater than zero that specifies how many
241              milliseconds to wait for each reply, or  the  atom  infinity  to
242              wait indefinitely. Defaults to infinity. If no reply is received
243              from a node within the specified time,  the  node  is  added  to
244              BadNodes.
245
246              When  a reply Reply is received from the gen_server process at a
247              node Node, {Node,Reply} is added to Replies. Reply is defined in
248              the return value of Module:handle_call/3.
249
250          Warning:
251              If  one  of the nodes cannot process monitors, for example, C or
252              Java nodes, and the gen_server process is not started  when  the
253              requests  are  sent,  but starts within 2 seconds, this function
254              waits the whole Timeout, which may be infinity.
255
256              This problem does not exist if all nodes are Erlang nodes.
257
258
259              To prevent late answers (after the time-out) from polluting  the
260              message  queue  of the caller, a middleman process is used to do
261              the calls. Late answers are then discarded when they arrive to a
262              terminated process.
263
264       reply(Client, Reply) -> Result
265
266              Types:
267
268                 Client - see below
269                 Reply = term()
270                 Result = term()
271
272              This  function can be used by a gen_server process to explicitly
273              send  a  reply   to   a   client   that   called   call/2,3   or
274              multi_call/2,3,4, when the reply cannot be defined in the return
275              value of Module:handle_call/3.
276
277              Client must be the From argument provided to the callback  func‐
278              tion.  Reply  is any term given back to the client as the return
279              value of call/2,3 or multi_call/2,3,4.
280
281              The return value Result is not further defined, and is always to
282              be ignored.
283
284       start(Module, Args, Options) -> Result
285       start(ServerName, Module, Args, Options) -> Result
286
287              Types:
288
289                 ServerName = {local,Name} | {global,GlobalName}
290                  | {via,Module,ViaName}
291                  Name = atom()
292                  GlobalName = ViaName = term()
293                 Module = atom()
294                 Args = term()
295                 Options = [Option]
296                  Option   =   {debug,Dbgs}   |   {timeout,Time}   |   {hiber‐
297                 nate_after,HibernateAfterTimeout} | {spawn_opt,SOpts}
298                  Dbgs = [Dbg]
299                  Dbg = trace | log | statistics  |  {log_to_file,FileName}  |
300                 {install,{Func,FuncState}}
301                  SOpts = [term()]
302                 Result = {ok,Pid} | ignore | {error,Error}
303                  Pid = pid()
304                  Error = {already_started,Pid} | term()
305
306              Creates  a  standalone gen_server process, that is, a gen_server
307              process that is not part of a supervision tree and thus  has  no
308              supervisor.
309
310              For   a   description   of  arguments  and  return  values,  see
311              start_link/3,4.
312
313       start_link(Module, Args, Options) -> Result
314       start_link(ServerName, Module, Args, Options) -> Result
315
316              Types:
317
318                 ServerName = {local,Name} | {global,GlobalName}
319                  | {via,Module,ViaName}
320                  Name = atom()
321                  GlobalName = ViaName = term()
322                 Module = atom()
323                 Args = term()
324                 Options = [Option]
325                  Option   =   {debug,Dbgs}   |   {timeout,Time}   |   {hiber‐
326                 nate_after,HibernateAfterTimeout} | {spawn_opt,SOpts}
327                  Dbgs = [Dbg]
328                  Dbg  =  trace  | log | statistics | {log_to_file,FileName} |
329                 {install,{Func,FuncState}}
330                  SOpts = [term()]
331                 Result = {ok,Pid} | ignore | {error,Error}
332                  Pid = pid()
333                  Error = {already_started,Pid} | term()
334
335              Creates a gen_server process as part of a supervision tree. This
336              function  is to be called, directly or indirectly, by the super‐
337              visor. For example, it ensures that the  gen_server  process  is
338              linked to the supervisor.
339
340              The  gen_server  process  calls  Module:init/1 to initialize. To
341              ensure a synchronized startup procedure, start_link/3,4 does not
342              return until Module:init/1 has returned.
343
344                * If ServerName={local,Name}, the gen_server process is regis‐
345                  tered locally as Name using register/2.
346
347                * If ServerName={global,GlobalName}, the gen_server process id
348                  registered   globally   as  GlobalName  using  global:regis‐
349                  ter_name/2 If no name is provided, the gen_server process is
350                  not registered.
351
352                * If  ServerName={via,Module,ViaName},  the gen_server process
353                  registers with the registry represented by Module. The  Mod‐
354                  ule  callback  is  to  export the functions register_name/2,
355                  unregister_name/1, whereis_name/1, and send/2, which are  to
356                  behave  like  the  corresponding  functions in global. Thus,
357                  {via,global,GlobalName} is a valid reference.
358
359              Module is the name of the callback module.
360
361              Args is any  term  that  is  passed  as  the  argument  to  Mod‐
362              ule:init/1.
363
364                * If  option {timeout,Time} is present, the gen_server process
365                  is allowed to spend Time milliseconds initializing or it  is
366                  terminated and the start function returns {error,timeout}.
367
368                * If    option    {hibernate_after,HibernateAfterTimeout}   is
369                  present, the  gen_server  process  awaits  any  message  for
370                  HibernateAfterTimeout  milliseconds  and  if  no  message is
371                  received, the process goes  into  hibernation  automatically
372                  (by calling proc_lib:hibernate/3).
373
374                * If  option  {debug,Dbgs}  is  present, the corresponding sys
375                  function is called for each item in Dbgs; see sys(3).
376
377                * If option {spawn_opt,SOpts} is present, SOpts is  passed  as
378                  option list to the spawn_opt BIF, which is used to spawn the
379                  gen_server process; see spawn_opt/2.
380
381          Note:
382              Using spawn option monitor is not allowed, it causes  the  func‐
383              tion to fail with reason badarg.
384
385
386              If  the  gen_server process is successfully created and initial‐
387              ized, the function returns {ok,Pid}, where Pid is the pid of the
388              gen_server  process.  If a process with the specified ServerName
389              exists        already,        the        function        returns
390              {error,{already_started,Pid}},  where  Pid  is  the  pid of that
391              process.
392
393              If  Module:init/1  fails  with  Reason,  the  function   returns
394              {error,Reason}.   If   Module:init/1  returns  {stop,Reason}  or
395              ignore, the process  is  terminated  and  the  function  returns
396              {error,Reason} or ignore, respectively.
397
398       stop(ServerRef) -> ok
399       stop(ServerRef, Reason, Timeout) -> ok
400
401              Types:
402
403                 ServerRef = Name | {Name,Node} | {global,GlobalName}
404                  | {via,Module,ViaName} | pid()
405                  Node = atom()
406                  GlobalName = ViaName = term()
407                 Reason = term()
408                 Timeout = int()>0 | infinity
409
410              Orders  a  generic  server to exit with the specified Reason and
411              waits for it to terminate. The  gen_server  process  calls  Mod‐
412              ule:terminate/2 before exiting.
413
414              The  function  returns  ok  if  the  server  terminates with the
415              expected reason. Any other  reason  than  normal,  shutdown,  or
416              {shutdown,Term}  causes  an error report to be issued using log‐
417              ger(3). The default Reason is normal.
418
419              Timeout is an integer greater than zero that specifies how  many
420              milliseconds  to  wait  for the server to terminate, or the atom
421              infinity to wait indefinitely.  Defaults  to  infinity.  If  the
422              server  has  not terminated within the specified time, a timeout
423              exception is raised.
424
425              If the process does not exist, a noproc exception is raised.
426

CALLBACK FUNCTIONS

428       The following functions are to be exported from a  gen_server  callback
429       module.
430

EXPORTS

432       Module:code_change(OldVsn,  State,  Extra)  -> {ok, NewState} | {error,
433       Reason}
434
435              Types:
436
437                 OldVsn = Vsn | {down, Vsn}
438                  Vsn = term()
439                 State = NewState = term()
440                 Extra = term()
441                 Reason = term()
442
443          Note:
444              This callback is optional, so callback modules need  not  export
445              it.  If a release upgrade/downgrade with Change={advanced,Extra}
446              specified in the appup file is  made  when  code_change/3  isn't
447              implemented the process will crash with an undef exit reason.
448
449
450              This  function  is  called by a gen_server process when it is to
451              update its internal state during  a  release  upgrade/downgrade,
452              that  is, when the instruction {update,Module,Change,...}, where
453              Change={advanced,Extra}, is specifed in the appup file. For more
454              information,  see  section  Release Handling Instructions in OTP
455              Design Principles.
456
457              For an upgrade, OldVsn is Vsn, and for a  downgrade,  OldVsn  is
458              {down,Vsn}.  Vsn  is  defined by the vsn attribute(s) of the old
459              version of the callback module Module. If no such  attribute  is
460              defined, the version is the checksum of the Beam file.
461
462              State is the internal state of the gen_server process.
463
464              Extra  is  passed  "as is" from the {advanced,Extra} part of the
465              update instruction.
466
467              If successful, the function must  return  the  updated  internal
468              state.
469
470              If  the  function  returns  {error,Reason},  the ongoing upgrade
471              fails and rolls back to the old release.
472
473       Module:format_status(Opt, [PDict, State]) -> Status
474
475              Types:
476
477                 Opt = normal | terminate
478                 PDict = [{Key, Value}]
479                 State = term()
480                 Status = term()
481
482          Note:
483              This callback is optional, so callback modules need  not  export
484              it.  The  gen_server module provides a default implementation of
485              this function that returns the callback module state.
486
487
488              This function is called by a gen_server process in the following
489              situations:
490
491                * One  of  sys:get_status/1,2 is invoked to get the gen_server
492                  status. Opt is set to the atom normal.
493
494                * The gen_server process terminates  abnormally  and  logs  an
495                  error. Opt is set to the atom terminate.
496
497              This  function is useful for changing the form and appearance of
498              the gen_server status for these cases. A callback module wishing
499              to  change  the  sys:get_status/1,2 return value, as well as how
500              its  status  appears  in  termination  error  logs,  exports  an
501              instance  of  format_status/2 that returns a term describing the
502              current status of the gen_server process.
503
504              PDict is the current value of  the  process  dictionary  of  the
505              gen_server process..
506
507              State is the internal state of the gen_server process.
508
509              The  function  is  to  return  Status,  a  term that changes the
510              details of the  current  state  and  status  of  the  gen_server
511              process.  There are no restrictions on the form Status can take,
512              but for the sys:get_status/1,2 case (when Opt  is  normal),  the
513              recommended  form  for  the  Status  value is [{data, [{"State",
514              Term}]}], where Term provides relevant details of the gen_server
515              state.  Following  this  recommendation  is not required, but it
516              makes the callback module status consistent with the rest of the
517              sys:get_status/1,2 return value.
518
519              One use for this function is to return compact alternative state
520              representations to avoid that large state terms are  printed  in
521              log files.
522
523       Module:handle_call(Request, From, State) -> Result
524
525              Types:
526
527                 Request = term()
528                 From = {pid(),Tag}
529                 State = term()
530                 Result = {reply,Reply,NewState} | {reply,Reply,NewState,Time‐
531                 out}
532                  | {reply,Reply,NewState,hibernate}
533                  | {reply,Reply,NewState,{continue,Continue}}
534                  | {noreply,NewState} | {noreply,NewState,Timeout}
535                  | {noreply,NewState,hibernate}
536                  | {noreply,NewState,{continue,Continue}}
537                  | {stop,Reason,Reply,NewState} | {stop,Reason,NewState}
538                  Reply = term()
539                  NewState = term()
540                  Timeout = int()>=0 | infinity
541                  Continue = term()
542                  Reason = term()
543
544              Whenever a gen_server process  receives  a  request  sent  using
545              call/2,3  or multi_call/2,3,4, this function is called to handle
546              the request.
547
548              Request is the Request argument provided to call or multi_call.
549
550              From is a tuple {Pid,Tag}, where Pid is the pid  of  the  client
551              and Tag is a unique tag.
552
553              State is the internal state of the gen_server process.
554
555                * If  {reply,Reply,NewState}  is  returned,  {reply,Reply,New‐
556                  State,Timeout} or {reply,Reply,NewState,hibernate}, Reply is
557                  given  back  to  From  as  the  return  value of call/2,3 or
558                  included  in  the  return  value  of  multi_call/2,3,4.  The
559                  gen_server  process then continues executing with the possi‐
560                  bly updated internal state NewState.
561
562                  For  a  description  of  Timeout  and  hibernate,  see  Mod‐
563                  ule:init/1.
564
565                * If  {noreply,NewState}  is returned, {noreply,NewState,Time‐
566                  out},  or   {noreply,NewState,hibernate},   the   gen_server
567                  process continues executing with NewState. Any reply to From
568                  must be specified explicitly using reply/2.
569
570                * If {stop,Reason,Reply,NewState} is returned, Reply is  given
571                  back to From.
572
573                * If  {stop,Reason,NewState}  is  returned,  any reply to From
574                  must be specified explicitly using reply/2.  The  gen_server
575                  process  then  calls  Module:terminate(Reason,NewState)  and
576                  terminates.
577
578       Module:handle_cast(Request, State) -> Result
579
580              Types:
581
582                 Request = term()
583                 State = term()
584                 Result = {noreply,NewState} | {noreply,NewState,Timeout}
585                  | {noreply,NewState,hibernate}
586                  | {noreply,NewState,{continue,Continue}}
587                  | {stop,Reason,NewState}
588                  NewState = term()
589                  Timeout = int()>=0 | infinity
590                  Continue = term()
591                  Reason = term()
592
593              Whenever a gen_server process  receives  a  request  sent  using
594              cast/2  or  abcast/2,3,  this  function  is called to handle the
595              request.
596
597              For a description of the arguments and possible  return  values,
598              see Module:handle_call/3.
599
600       Module:handle_continue(Continue, State) -> Result
601
602              Types:
603
604                 Continue = term()
605                 State = term()
606                 Result = {noreply,NewState} | {noreply,NewState,Timeout}
607                  | {noreply,NewState,hibernate}
608                  | {noreply,NewState,{continue,Continue}}
609                  | {stop,Reason,NewState}
610                  NewState = term()
611                  Timeout = int()>=0 | infinity
612                  Continue = term()
613                  Reason = normal | term()
614
615          Note:
616              This callback is optional, so callback modules need to export it
617              only if they return {continue,Continue} from  another  callback.
618              If  continue  is  used  and the callback is not implemented, the
619              process will exit with undef error.
620
621
622              This function is called by a gen_server process whenever a  pre‐
623              vious  callback  returns {continue, Continue}. handle_continue/2
624              is invoked immediately after the previous callback, which  makes
625              it useful for performing work after initialization or for split‐
626              ting the work in a callback  in  multiple  steps,  updating  the
627              process state along the way.
628
629              For  a  description  of  the other arguments and possible return
630              values, see Module:handle_call/3.
631
632       Module:handle_info(Info, State) -> Result
633
634              Types:
635
636                 Info = timeout | term()
637                 State = term()
638                 Result = {noreply,NewState} | {noreply,NewState,Timeout}
639                  | {noreply,NewState,hibernate}
640                  | {noreply,NewState,{continue,Continue}}
641                  | {stop,Reason,NewState}
642                  NewState = term()
643                  Timeout = int()>=0 | infinity
644                  Reason = normal | term()
645
646          Note:
647              This callback is optional, so callback modules need  not  export
648              it.  The  gen_server module provides a default implementation of
649              this function that logs about the unexpected Info message, drops
650              it and returns {noreply, State}.
651
652
653              This  function is called by a gen_server process when a time-out
654              occurs or when it receives any other message than a  synchronous
655              or asynchronous request (or a system message).
656
657              Info  is either the atom timeout, if a time-out has occurred, or
658              the received message.
659
660              For a description of the other  arguments  and  possible  return
661              values, see Module:handle_call/3.
662
663       Module:init(Args) -> Result
664
665              Types:
666
667                 Args = term()
668                 Result  =  {ok,State} | {ok,State,Timeout} | {ok,State,hiber‐
669                 nate}
670                  | {ok,State,{continue,Continue}} | {stop,Reason} | ignore
671                  State = term()
672                  Timeout = int()>=0 | infinity
673                  Reason = term()
674
675              Whenever a gen_server process  is  started  using  start/3,4  or
676              start_link/3,4,  this  function  is called by the new process to
677              initialize.
678
679              Args is the Args argument provided to the start function.
680
681              If the initialization is successful, the function is  to  return
682              {ok,State},  {ok,State,Timeout},  or {ok,State,hibernate}, where
683              State is the internal state of the gen_server process.
684
685              If an integer time-out value  is  provided,  a  time-out  occurs
686              unless  a  request  or a message is received within Timeout mil‐
687              liseconds. A time-out is represented by the atom timeout,  which
688              is  to be handled by the Module:handle_info/2 callback function.
689              The atom infinity can be used to wait indefinitely, this is  the
690              default value.
691
692              If  hibernate  is  specified  instead  of  a time-out value, the
693              process goes into hibernation when waiting for the next  message
694              to arrive (by calling proc_lib:hibernate/3).
695
696              If   the   initialization  fails,  the  function  is  to  return
697              {stop,Reason}, where Reason is any term, or ignore.
698
699       Module:terminate(Reason, State)
700
701              Types:
702
703                 Reason = normal | shutdown | {shutdown,term()} | term()
704                 State = term()
705
706          Note:
707              This callback is optional, so callback modules need  not  export
708              it.  The  gen_server  module  provides  a default implementation
709              without cleanup.
710
711
712              This function is called by a gen_server process when it is about
713              to  terminate.  It is to be the opposite of Module:init/1 and do
714              any necessary cleaning  up.  When  it  returns,  the  gen_server
715              process terminates with Reason. The return value is ignored.
716
717              Reason  is  a  term  denoting  the  stop reason and State is the
718              internal state of the gen_server process.
719
720              Reason depends on why the gen_server process is terminating.  If
721              it  is  because  another  callback  function has returned a stop
722              tuple {stop,..}, Reason has the value specified in  that  tuple.
723              If it is because of a failure, Reason is the error reason.
724
725              If  the  gen_server process is part of a supervision tree and is
726              ordered by its supervisor to terminate, this function is  called
727              with Reason=shutdown if the following conditions apply:
728
729                * The gen_server process has been set to trap exit signals.
730
731                * The  shutdown strategy as defined in the child specification
732                  of the supervisor is an integer  time-out  value,  not  bru‐
733                  tal_kill.
734
735              Even  if  the  gen_server  process  is not part of a supervision
736              tree, this function is called if it receives an  'EXIT'  message
737              from its parent. Reason is the same as in the 'EXIT' message.
738
739              Otherwise, the gen_server process terminates immediately.
740
741              Notice  that  for  any  other  reason  than normal, shutdown, or
742              {shutdown,Term}, the gen_server process is assumed to  terminate
743              because  of  an  error  and an error report is issued using log‐
744              ger(3).
745

SEE ALSO

747       gen_event(3), gen_statem(3), proc_lib(3), supervisor(3), sys(3)
748
749
750
751Ericsson AB                      stdlib 3.12.1                   gen_server(3)
Impressum