1gen_server(3) Erlang Module Definition gen_server(3)
2
6 gen_server - Generic server behavior.
7
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 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 gen_server module Callback module
22 ----------------- ---------------
23 gen_server:start
24 gen_server:start_monitor
25 gen_server:start_link -----> Module:init/1
26 gen_server:stop -----> Module:terminate/2
28 gen_server:call
30 gen_server:send_request
31 gen_server:multi_call -----> Module:handle_call/3
32 gen_server:cast
34 gen_server:abcast -----> Module:handle_cast/2
35 - -----> Module:handle_info/2
37 - -----> Module:handle_continue/2
39 - -----> Module:terminate/2
41 - -----> Module:code_change/3
43 If a callback function fails or returns a bad value, the gen_server
45 process terminates.
46 A gen_server process handles system messages as described in sys(3).
48 The sys module can be used for debugging a gen_server process.
49 Notice that a gen_server process does not trap exit signals automati‐
51 cally, this must be explicitly initiated in the callback module.
52 Unless otherwise stated, all functions in this module fail if the spec‐
54 ified gen_server process does not exist or if bad arguments are speci‐
55 fied.
56 The gen_server process can go into hibernation (see erlang:hibernate/3)
58 if a callback function specifies 'hibernate' instead of a time-out
59 value. This can be useful if the server is expected to be idle for a
60 long time. However, use this feature with care, as hibernation implies
61 at least two garbage collections (when hibernating and shortly after
62 waking up) and is not something you want to do between each call to a
63 busy server.
64 If the gen_server process needs to perform an action immediately after
66 initialization or to break the execution of a callback into multiple
67 steps, it can return {continue,Continue} in place of the time-out or
68 hibernation value, which will immediately invoke the handle_continue/2
69 callback.
70
72 abcast(Name, Request) -> abcast
73 abcast(Nodes, Name, Request) -> abcast
74 Types:
76 Nodes = [Node]
78 Node = atom()
79 Name = atom()
80 Request = term()
81 Sends an asynchronous request to the gen_server processes lo‐
83 cally registered as Name at the specified nodes. The function
84 returns immediately and ignores nodes that do not exist, or
85 where the gen_server Name does not exist. The gen_server pro‐
86 cesses call Module:handle_cast/2 to handle the request.
87 For a description of the arguments, see multi_call/2,3,4.
89 call(ServerRef, Request) -> Reply
91 call(ServerRef, Request, Timeout) -> Reply
92 Types:
94 ServerRef = Name | {Name,Node} | {global,GlobalName}
96 | {via,Module,ViaName} | pid()
97 Node = atom()
98 GlobalName = ViaName = term()
99 Request = term()
100 Timeout = int()>0 | infinity
101 Reply = term()
102 Makes a synchronous call to the ServerRef of the gen_server
104 process by sending a request and waiting until a reply arrives
105 or a time-out occurs. The gen_server process calls Module:han‐
106 dle_call/3 to handle the request.
107 ServerRef can be any of the following:
109 * The pid
111 * Name, if the gen_server process is locally registered
113 * {Name,Node}, if the gen_server process is locally registered
115 at another node
116 * {global,GlobalName}, if the gen_server process is globally
118 registered
119 * {via,Module,ViaName}, if the gen_server process is regis‐
121 tered through an alternative process registry
122 Request is any term that is passed as the first argument to Mod‐
124 ule:handle_call/3.
125 Timeout is an integer greater than zero that specifies how many
127 milliseconds to wait for a reply, or the atom infinity to wait
128 indefinitely. Defaults to 5000. If no reply is received within
129 the specified time, the function call fails. If the caller
130 catches the failure and continues running, and the server is
131 just late with the reply, it can arrive at any time later into
132 the message queue of the caller. The caller must in this case be
133 prepared for this and discard any such garbage messages that are
134 two element tuples with a reference as the first element.
135 The return value Reply is defined in the return value of Mod‐
137 ule:handle_call/3.
138 The call can fail for many reasons, including time-out and the
140 called gen_server process dying before or during the call.
141 cast(ServerRef, Request) -> ok
143 Types:
145 ServerRef = Name | {Name,Node} | {global,GlobalName}
147 | {via,Module,ViaName} | pid()
148 Node = atom()
149 GlobalName = ViaName = term()
150 Request = term()
151 Sends an asynchronous request to the ServerRef of the gen_server
153 process and returns ok immediately, ignoring if the destination
154 node or gen_server process does not exist. The gen_server
155 process calls Module:handle_cast/2 to handle the request.
156 For a description of ServerRef, see call/2,3.
158 Request is any term that is passed as one of the arguments to
160 Module:handle_cast/2.
161 check_response(Msg, RequestId) -> Result
163 Types:
165 RequestId = term()
167 Result = {reply, Reply} | no_reply | {error, {Reason, Server‐
168 Ref}}
169 Msg = Reply = term()
170 Timeout = timeout()
171 Reason = term()
172 ServerRef = Name | {Name,Node} | {global,GlobalName}
173 | {via,Module,ViaName} | pid()
174 Node = atom()
175 GlobalName = ViaName = term()
176 This function is used to check if a previously received message,
178 for example by receive or handle_info/2, is a result of a re‐
179 quest made with send_request/2. If Msg is a reply to the handle
180 RequestId the result of the request is returned in Reply. Other‐
181 wise returns no_reply and no cleanup is done, and thus the func‐
182 tion must be invoked repeatedly until a reply is returned.
183 The return value Reply is defined in the return value of Mod‐
185 ule:handle_call/3.
186 The function returns an error if the gen_server dies before or
188 during this request.
189 enter_loop(Module, Options, State)
191 enter_loop(Module, Options, State, ServerName)
192 enter_loop(Module, Options, State, Timeout)
193 enter_loop(Module, Options, State, ServerName, Timeout)
194 Types:
196 Module = atom()
198 Options = [Option]
199 Option = {debug,Dbgs} | {hibernate_after,HibernateAfterTime‐
200 out}
201 Dbgs = [Dbg]
202 Dbg = trace | log | statistics
203 | {log_to_file,FileName} | {install,{Func,FuncState}}
204 State = term()
205 ServerName = {local,Name} | {global,GlobalName}
206 | {via,Module,ViaName}
207 Name = atom()
208 GlobalName = ViaName = term()
209 Timeout = int() | infinity
210 Makes an existing process into a gen_server process. Does not
212 return, instead the calling process enters the gen_server
213 process receive loop and becomes a gen_server process. The
214 process must have been started using one of the start functions
215 in proc_lib(3). The user is responsible for any initialization
216 of the process, including registering a name for it.
217 This function is useful when a more complex initialization pro‐
219 cedure is needed than the gen_server process behavior provides.
220 Module, Options, and ServerName have the same meanings as when
222 calling start[_link|_monitor]/3,4. However, if ServerName is
223 specified, the process must have been registered accordingly be‐
224 fore this function is called.
225 State and Timeout have the same meanings as in the return value
227 of Module:init/1. The callback module Module does not need to
228 export an init/1 function.
229 The function fails if the calling process was not started by a
231 proc_lib start function, or if it is not registered according to
232 ServerName.
233 multi_call(Name, Request) -> Result
235 multi_call(Nodes, Name, Request) -> Result
236 multi_call(Nodes, Name, Request, Timeout) -> Result
237 Types:
239 Nodes = [Node]
241 Node = atom()
242 Name = atom()
243 Request = term()
244 Timeout = int()>=0 | infinity
245 Result = {Replies,BadNodes}
246 Replies = [{Node,Reply}]
247 Reply = term()
248 BadNodes = [Node]
249 Makes a synchronous call to all gen_server processes locally
251 registered as Name at the specified nodes by first sending a re‐
252 quest to every node and then waits for the replies. The
253 gen_server process calls Module:handle_call/3 to handle the re‐
254 quest.
255 The function returns a tuple {Replies,BadNodes}, where Replies
257 is a list of {Node,Reply} and BadNodes is a list of node that
258 either did not exist, or where the gen_server Name did not exist
259 or did not reply.
260 Nodes is a list of node names to which the request is to be
262 sent. Default value is the list of all known nodes
263 [node()|nodes()].
264 Name is the locally registered name of each gen_server process.
266 Request is any term that is passed as the first argument to Mod‐
268 ule:handle_call/3.
269 Timeout is an integer greater than zero that specifies how many
271 milliseconds to wait for each reply, or the atom infinity to
272 wait indefinitely. Defaults to infinity. If no reply is received
273 from a node within the specified time, the node is added to
274 BadNodes.
275 When a reply Reply is received from the gen_server process at a
277 node Node, {Node,Reply} is added to Replies. Reply is defined in
278 the return value of Module:handle_call/3.
279 Warning:
281 If one of the nodes cannot process monitors, for example, C or
282 Java nodes, and the gen_server process is not started when the
283 requests are sent, but starts within 2 seconds, this function
284 waits the whole Timeout, which may be infinity.
285 This problem does not exist if all nodes are Erlang nodes.
287 To prevent late answers (after the time-out) from polluting the
290 message queue of the caller, a middleman process is used to do
291 the calls. Late answers are then discarded when they arrive to a
292 terminated process.
293 reply(Client, Reply) -> ok
295 Types:
297 Client - see below
299 Reply = term()
300 This function can be used by a gen_server process to explicitly
302 send a reply to a client that called call/2,3 or
303 multi_call/2,3,4, when the reply cannot be defined in the return
304 value of Module:handle_call/3.
305 Client must be the From argument provided to the callback func‐
307 tion. Reply is any term given back to the client as the return
308 value of call/2,3 or multi_call/2,3,4.
309 send_request(ServerRef, Request) -> RequestId
311 Types:
313 ServerRef = Name | {Name,Node} | {global,GlobalName}
315 | {via,Module,ViaName} | pid()
316 Node = atom()
317 GlobalName = ViaName = term()
318 RequestId = term()
319 Timeout = int()>0 | infinity
320 Request = term()
321 Sends a request to the ServerRef of the gen_server process and
323 returns a handle RequestId. The return value RequestId shall
324 later be used with wait_response/2 or check_response/2 to fetch
325 the actual result of the request.
326 The call gen_server:wait_response(gen_server:send_re‐
328 quest(ServerRef,Request), Timeout) can be seen as equivalent to
329 gen_server:call(Server,Request,Timeout), ignoring the error han‐
330 dling.
331 The gen_server process calls Module:handle_call/3 to handle the
333 request.
334 ServerRef can be any of the following:
336 * The pid
338 * Name, if the gen_server process is locally registered
340 * {Name,Node}, if the gen_server process is locally registered
342 at another node
343 * {global,GlobalName}, if the gen_server process is globally
345 registered
346 * {via,Module,ViaName}, if the gen_server process is regis‐
348 tered through an alternative process registry
349 Request is any term that is passed as the first argument to Mod‐
351 ule:handle_call/3.
352 start(Module, Args, Options) -> Result
354 start(ServerName, Module, Args, Options) -> Result
355 Types:
357 ServerName = {local,Name} | {global,GlobalName}
359 | {via,Module,ViaName}
360 Name = atom()
361 GlobalName = ViaName = term()
362 Module = atom()
363 Args = term()
364 Options = [Option]
365 Option = {debug,Dbgs} | {timeout,Time} | {hibernate_af‐
366 ter,HibernateAfterTimeout} | {spawn_opt,SOpts}
367 Dbgs = [Dbg]
368 Dbg = trace | log | statistics | {log_to_file,FileName} |
369 {install,{Func,FuncState}}
370 SOpts = [term()]
371 Result = {ok,Pid} | ignore | {error,Error}
372 Pid = pid()
373 Error = {already_started,Pid} | term()
374 Creates a standalone gen_server process, that is, a gen_server
376 process that is not part of a supervision tree and thus has no
377 supervisor.
378 For a description of arguments and return values, see
380 start_link/3,4.
381 start_link(Module, Args, Options) -> Result
383 start_link(ServerName, Module, Args, Options) -> Result
384 Types:
386 ServerName = {local,Name} | {global,GlobalName}
388 | {via,Module,ViaName}
389 Name = atom()
390 GlobalName = ViaName = term()
391 Module = atom()
392 Args = term()
393 Options = [Option]
394 Option = {debug,Dbgs} | {timeout,Time} | {hibernate_af‐
395 ter,HibernateAfterTimeout} | {spawn_opt,SOpts}
396 Dbgs = [Dbg]
397 Dbg = trace | log | statistics | {log_to_file,FileName} |
398 {install,{Func,FuncState}}
399 SOpts = [term()]
400 Result = {ok,Pid} | ignore | {error,Error}
401 Pid = pid()
402 Error = {already_started,Pid} | term()
403 Creates a gen_server process as part of a supervision tree. This
405 function is to be called, directly or indirectly, by the super‐
406 visor. For example, it ensures that the gen_server process is
407 linked to the supervisor.
408 The gen_server process calls Module:init/1 to initialize. To en‐
410 sure a synchronized startup procedure, start_link/3,4 does not
411 return until Module:init/1 has returned.
412 * If ServerName={local,Name}, the gen_server process is regis‐
414 tered locally as Name using register/2.
415 * If ServerName={global,GlobalName}, the gen_server process id
417 registered globally as GlobalName using global:regis‐
418 ter_name/2 If no name is provided, the gen_server process is
419 not registered.
420 * If ServerName={via,Module,ViaName}, the gen_server process
422 registers with the registry represented by Module. The Mod‐
423 ule callback is to export the functions register_name/2, un‐
424 register_name/1, whereis_name/1, and send/2, which are to
425 behave like the corresponding functions in global. Thus,
426 {via,global,GlobalName} is a valid reference.
427 Module is the name of the callback module.
429 Args is any term that is passed as the argument to Mod‐
431 ule:init/1.
432 * If option {timeout,Time} is present, the gen_server process
434 is allowed to spend Time milliseconds initializing or it is
435 terminated and the start function returns {error,timeout}.
436 * If option {hibernate_after,HibernateAfterTimeout} is
438 present, the gen_server process awaits any message for Hi‐
439 bernateAfterTimeout milliseconds and if no message is re‐
440 ceived, the process goes into hibernation automatically (by
441 calling proc_lib:hibernate/3).
442 * If option {debug,Dbgs} is present, the corresponding sys
444 function is called for each item in Dbgs; see sys(3).
445 * If option {spawn_opt,SOpts} is present, SOpts is passed as
447 option list to the spawn_opt BIF, which is used to spawn the
448 gen_server process; see spawn_opt/2.
449 Note:
451 Using spawn option monitor is not allowed, it causes the func‐
452 tion to fail with reason badarg.
453 If the gen_server process is successfully created and initial‐
456 ized, the function returns {ok,Pid}, where Pid is the pid of the
457 gen_server process. If a process with the specified ServerName
458 exists already, the function returns {error,{al‐
459 ready_started,Pid}}, where Pid is the pid of that process.
460 If Module:init/1 fails with Reason, the function returns {er‐
462 ror,Reason}. If Module:init/1 returns {stop,Reason} or ignore,
463 the process is terminated and the function returns {error,Rea‐
464 son} or ignore, respectively.
465 start_monitor(Module, Args, Options) -> Result
467 start_monitor(ServerName, Module, Args, Options) -> Result
468 Types:
470 ServerName = {local,Name} | {global,GlobalName}
472 | {via,Module,ViaName}
473 Name = atom()
474 GlobalName = ViaName = term()
475 Module = atom()
476 Args = term()
477 Options = [Option]
478 Option = {debug,Dbgs} | {timeout,Time} | {hibernate_af‐
479 ter,HibernateAfterTimeout} | {spawn_opt,SOpts}
480 Dbgs = [Dbg]
481 Dbg = trace | log | statistics | {log_to_file,FileName} |
482 {install,{Func,FuncState}}
483 SOpts = [term()]
484 Result = {ok,{Pid,Mon}} | ignore | {error,Error}
485 Pid = pid()
486 Error = {already_started,Pid} | term()
487 Creates a standalone gen_server process, that is, a gen_server
489 process that is not part of a supervision tree (and thus has no
490 supervisor) and atomically sets up a monitor to the newly cre‐
491 ated server.
492 For a description of arguments and return values, see
494 start_link/3,4. Note that the return value on successful start
495 differs from start_link/3,4. start_monitor/3,4 will return
496 {ok,{Pid,Mon}} where Pid is the process identifier of the
497 server, and Mon is a reference to the monitor set up to monitor
498 the server. If the start is not successful, the caller will be
499 blocked until the DOWN message has been received and removed
500 from the message queue.
501 stop(ServerRef) -> ok
503 stop(ServerRef, Reason, Timeout) -> ok
504 Types:
506 ServerRef = Name | {Name,Node} | {global,GlobalName}
508 | {via,Module,ViaName} | pid()
509 Node = atom()
510 GlobalName = ViaName = term()
511 Reason = term()
512 Timeout = int()>0 | infinity
513 Orders a generic server to exit with the specified Reason and
515 waits for it to terminate. The gen_server process calls Mod‐
516 ule:terminate/2 before exiting.
517 The function returns ok if the server terminates with the ex‐
519 pected reason. Any other reason than normal, shutdown, or {shut‐
520 down,Term} causes an error report to be issued using logger(3).
521 The default Reason is normal.
522 Timeout is an integer greater than zero that specifies how many
524 milliseconds to wait for the server to terminate, or the atom
525 infinity to wait indefinitely. Defaults to infinity. If the
526 server has not terminated within the specified time, a timeout
527 exception is raised.
528 If the process does not exist, a noproc exception is raised.
530 wait_response(RequestId, Timeout) -> Result
532 Types:
534 RequestId = term()
536 Result = {reply, Reply} | timeout | {error, {Reason, Server‐
537 Ref}}
538 Reply = term()
539 Timeout = timeout()
540 Reason = term()
541 ServerRef = Name | {Name,Node} | {global,GlobalName}
542 | {via,Module,ViaName} | pid()
543 Node = atom()
544 GlobalName = ViaName = term()
545 This function is used to wait for a reply of a request made with
547 send_request/2 from the gen_server process. This function must
548 be called from the same process from which send_request/2 was
549 made.
550 Timeout is an integer greater then or equal to zero that speci‐
552 fies how many milliseconds to wait for an reply, or the atom in‐
553 finity to wait indefinitely. If no reply is received within the
554 specified time, the function returns timeout and no cleanup is
555 done, and thus the function can be invoked repeatedly until a
556 reply is returned.
557 The return value Reply is defined in the return value of Mod‐
559 ule:handle_call/3.
560 The function returns an error if the gen_server dies before or
562 during this request.
563
565 The following functions are to be exported from a gen_server callback
566 module.
567
569 Module:code_change(OldVsn, State, Extra) -> {ok, NewState} | {error,
570 Reason}
571 Types:
573 OldVsn = Vsn | {down, Vsn}
575 Vsn = term()
576 State = NewState = term()
577 Extra = term()
578 Reason = term()
579 Note:
581 This callback is optional, so callback modules need not export
582 it. If a release upgrade/downgrade with Change={advanced,Extra}
583 specified in the appup file is made when code_change/3 isn't im‐
584 plemented the process will crash with an undef exit reason.
585 This function is called by a gen_server process when it is to
588 update its internal state during a release upgrade/downgrade,
589 that is, when the instruction {update,Module,Change,...}, where
590 Change={advanced,Extra}, is specifed in the appup file. For more
591 information, see section Release Handling Instructions in OTP
592 Design Principles.
593 For an upgrade, OldVsn is Vsn, and for a downgrade, OldVsn is
595 {down,Vsn}. Vsn is defined by the vsn attribute(s) of the old
596 version of the callback module Module. If no such attribute is
597 defined, the version is the checksum of the Beam file.
598 State is the internal state of the gen_server process.
600 Extra is passed "as is" from the {advanced,Extra} part of the
602 update instruction.
603 If successful, the function must return the updated internal
605 state.
606 If the function returns {error,Reason}, the ongoing upgrade
608 fails and rolls back to the old release.
609 Module:format_status(Opt, [PDict, State]) -> Status
611 Types:
613 Opt = normal | terminate
615 PDict = [{Key, Value}]
616 State = term()
617 Status = term()
618 Note:
620 This callback is optional, so callback modules need not export
621 it. The gen_server module provides a default implementation of
622 this function that returns the callback module state.
623 This function is called by a gen_server process in the following
626 situations:
627 * One of sys:get_status/1,2 is invoked to get the gen_server
629 status. Opt is set to the atom normal.
630 * The gen_server process terminates abnormally and logs an er‐
632 ror. Opt is set to the atom terminate.
633 This function is useful for changing the form and appearance of
635 the gen_server status for these cases. A callback module wishing
636 to change the sys:get_status/1,2 return value, as well as how
637 its status appears in termination error logs, exports an in‐
638 stance of format_status/2 that returns a term describing the
639 current status of the gen_server process.
640 PDict is the current value of the process dictionary of the
642 gen_server process..
643 State is the internal state of the gen_server process.
645 The function is to return Status, a term that changes the de‐
647 tails of the current state and status of the gen_server process.
648 There are no restrictions on the form Status can take, but for
649 the sys:get_status/1,2 case (when Opt is normal), the recom‐
650 mended form for the Status value is [{data, [{"State", Term}]}],
651 where Term provides relevant details of the gen_server state.
652 Following this recommendation is not required, but it makes the
653 callback module status consistent with the rest of the
654 sys:get_status/1,2 return value.
655 One use for this function is to return compact alternative state
657 representations to avoid that large state terms are printed in
658 log files.
659 Module:handle_call(Request, From, State) -> Result
661 Types:
663 Request = term()
665 From = {pid(),Tag}
666 State = term()
667 Result = {reply,Reply,NewState} | {reply,Reply,NewState,Time‐
668 out}
669 | {reply,Reply,NewState,hibernate}
670 | {reply,Reply,NewState,{continue,Continue}}
671 | {noreply,NewState} | {noreply,NewState,Timeout}
672 | {noreply,NewState,hibernate}
673 | {noreply,NewState,{continue,Continue}}
674 | {stop,Reason,Reply,NewState} | {stop,Reason,NewState}
675 Reply = term()
676 NewState = term()
677 Timeout = int()>=0 | infinity
678 Continue = term()
679 Reason = term()
680 Whenever a gen_server process receives a request sent using
682 call/2,3 or multi_call/2,3,4, this function is called to handle
683 the request.
684 Request is the Request argument provided to call or multi_call.
686 From is a tuple {Pid,Tag}, where Pid is the pid of the client
688 and Tag is a unique tag.
689 State is the internal state of the gen_server process.
691 * If {reply,Reply,NewState} is returned, {reply,Reply,New‐
693 State,Timeout} or {reply,Reply,NewState,hibernate}, Reply is
694 given back to From as the return value of call/2,3 or in‐
695 cluded in the return value of multi_call/2,3,4. The
696 gen_server process then continues executing with the possi‐
697 bly updated internal state NewState.
698 For a description of Timeout and hibernate, see Mod‐
700 ule:init/1.
701 * If {noreply,NewState} is returned, {noreply,NewState,Time‐
703 out}, or {noreply,NewState,hibernate}, the gen_server
704 process continues executing with NewState. Any reply to From
705 must be specified explicitly using reply/2.
706 * If {stop,Reason,Reply,NewState} is returned, Reply is given
708 back to From.
709 * If {stop,Reason,NewState} is returned, any reply to From
711 must be specified explicitly using reply/2. The gen_server
712 process then calls Module:terminate(Reason,NewState) and
713 terminates.
714 Module:handle_cast(Request, State) -> Result
716 Types:
718 Request = term()
720 State = term()
721 Result = {noreply,NewState} | {noreply,NewState,Timeout}
722 | {noreply,NewState,hibernate}
723 | {noreply,NewState,{continue,Continue}}
724 | {stop,Reason,NewState}
725 NewState = term()
726 Timeout = int()>=0 | infinity
727 Continue = term()
728 Reason = term()
729 Whenever a gen_server process receives a request sent using
731 cast/2 or abcast/2,3, this function is called to handle the re‐
732 quest.
733 For a description of the arguments and possible return values,
735 see Module:handle_call/3.
736 Module:handle_continue(Continue, State) -> Result
738 Types:
740 Continue = term()
742 State = term()
743 Result = {noreply,NewState} | {noreply,NewState,Timeout}
744 | {noreply,NewState,hibernate}
745 | {noreply,NewState,{continue,Continue}}
746 | {stop,Reason,NewState}
747 NewState = term()
748 Timeout = int()>=0 | infinity
749 Continue = term()
750 Reason = normal | term()
751 Note:
753 This callback is optional, so callback modules need to export it
754 only if they return {continue,Continue} from another callback.
755 If continue is used and the callback is not implemented, the
756 process will exit with undef error.
757 This function is called by a gen_server process whenever a pre‐
760 vious callback returns {continue, Continue}. handle_continue/2
761 is invoked immediately after the previous callback, which makes
762 it useful for performing work after initialization or for split‐
763 ting the work in a callback in multiple steps, updating the
764 process state along the way.
765 For a description of the other arguments and possible return
767 values, see Module:handle_call/3.
768 Module:handle_info(Info, State) -> Result
770 Types:
772 Info = timeout | term()
774 State = term()
775 Result = {noreply,NewState} | {noreply,NewState,Timeout}
776 | {noreply,NewState,hibernate}
777 | {noreply,NewState,{continue,Continue}}
778 | {stop,Reason,NewState}
779 NewState = term()
780 Timeout = int()>=0 | infinity
781 Reason = normal | term()
782 Note:
784 This callback is optional, so callback modules need not export
785 it. The gen_server module provides a default implementation of
786 this function that logs about the unexpected Info message, drops
787 it and returns {noreply, State}.
788 This function is called by a gen_server process when a time-out
791 occurs or when it receives any other message than a synchronous
792 or asynchronous request (or a system message).
793 Info is either the atom timeout, if a time-out has occurred, or
795 the received message.
796 For a description of the other arguments and possible return
798 values, see Module:handle_call/3.
799 Module:init(Args) -> Result
801 Types:
803 Args = term()
805 Result = {ok,State} | {ok,State,Timeout} | {ok,State,hiber‐
806 nate}
807 | {ok,State,{continue,Continue}} | {stop,Reason} | ignore
808 State = term()
809 Timeout = int()>=0 | infinity
810 Reason = term()
811 Whenever a gen_server process is started using start/3,4,
813 start_monitor/3,4, or start_link/3,4, this function is called by
814 the new process to initialize.
815 Args is the Args argument provided to the start function.
817 If the initialization is successful, the function is to return
819 {ok,State}, {ok,State,Timeout}, or {ok,State,hibernate}, where
820 State is the internal state of the gen_server process.
821 If an integer time-out value is provided, a time-out occurs un‐
823 less a request or a message is received within Timeout millisec‐
824 onds. A time-out is represented by the atom timeout, which is to
825 be handled by the Module:handle_info/2 callback function. The
826 atom infinity can be used to wait indefinitely, this is the de‐
827 fault value.
828 If hibernate is specified instead of a time-out value, the
830 process goes into hibernation when waiting for the next message
831 to arrive (by calling proc_lib:hibernate/3).
832 If the initialization fails, the function is to return
834 {stop,Reason}, where Reason is any term, or ignore.
835 Module:terminate(Reason, State)
837 Types:
839 Reason = normal | shutdown | {shutdown,term()} | term()
841 State = term()
842 Note:
844 This callback is optional, so callback modules need not export
845 it. The gen_server module provides a default implementation
846 without cleanup.
847 This function is called by a gen_server process when it is about
850 to terminate. It is to be the opposite of Module:init/1 and do
851 any necessary cleaning up. When it returns, the gen_server
852 process terminates with Reason. The return value is ignored.
853 Reason is a term denoting the stop reason and State is the in‐
855 ternal state of the gen_server process.
856 Reason depends on why the gen_server process is terminating. If
858 it is because another callback function has returned a stop tu‐
859 ple {stop,..}, Reason has the value specified in that tuple. If
860 it is because of a failure, Reason is the error reason.
861 If the gen_server process is part of a supervision tree and is
863 ordered by its supervisor to terminate, this function is called
864 with Reason=shutdown if the following conditions apply:
865 * The gen_server process has been set to trap exit signals.
867 * The shutdown strategy as defined in the child specification
869 of the supervisor is an integer time-out value, not bru‐
870 tal_kill.
871 Even if the gen_server process is not part of a supervision
873 tree, this function is called if it receives an 'EXIT' message
874 from its parent. Reason is the same as in the 'EXIT' message.
875 Otherwise, the gen_server process terminates immediately.
877 Notice that for any other reason than normal, shutdown, or
879 {shutdown,Term}, the gen_server process is assumed to terminate
880 because of an error and an error report is issued using log‐
881 ger(3).
882
884 gen_event(3), gen_statem(3), proc_lib(3), supervisor(3), sys(3)
885Ericsson AB stdlib 3.14.2.1 gen_server(3)