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
83 locally 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
179 request made with send_request/2. If Msg is a reply to the han‐
180 dle RequestId the result of the request is returned in Reply.
181 Otherwise returns no_reply and no cleanup is done, and thus the
182 function 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
224 before 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
252 request to every node and then waits for the replies. The
253 gen_server process calls Module:handle_call/3 to handle the
254 request.
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
328 gen_server:wait_response(gen_server:send_request(Server‐
329 Ref,Request), Timeout) can be seen as equivalent to
330 gen_server:call(Server,Request,Timeout), ignoring the error han‐
331 dling.
332 The gen_server process calls Module:handle_call/3 to handle the
334 request.
335 ServerRef can be any of the following:
337 * The pid
339 * Name, if the gen_server process is locally registered
341 * {Name,Node}, if the gen_server process is locally registered
343 at another node
344 * {global,GlobalName}, if the gen_server process is globally
346 registered
347 * {via,Module,ViaName}, if the gen_server process is regis‐
349 tered through an alternative process registry
350 Request is any term that is passed as the first argument to Mod‐
352 ule:handle_call/3.
353 start(Module, Args, Options) -> Result
355 start(ServerName, Module, Args, Options) -> Result
356 Types:
358 ServerName = {local,Name} | {global,GlobalName}
360 | {via,Module,ViaName}
361 Name = atom()
362 GlobalName = ViaName = term()
363 Module = atom()
364 Args = term()
365 Options = [Option]
366 Option = {debug,Dbgs} | {timeout,Time} | {hiber‐
367 nate_after,HibernateAfterTimeout} | {spawn_opt,SOpts}
368 Dbgs = [Dbg]
369 Dbg = trace | log | statistics | {log_to_file,FileName} |
370 {install,{Func,FuncState}}
371 SOpts = [term()]
372 Result = {ok,Pid} | ignore | {error,Error}
373 Pid = pid()
374 Error = {already_started,Pid} | term()
375 Creates a standalone gen_server process, that is, a gen_server
377 process that is not part of a supervision tree and thus has no
378 supervisor.
379 For a description of arguments and return values, see
381 start_link/3,4.
382 start_link(Module, Args, Options) -> Result
384 start_link(ServerName, Module, Args, Options) -> Result
385 Types:
387 ServerName = {local,Name} | {global,GlobalName}
389 | {via,Module,ViaName}
390 Name = atom()
391 GlobalName = ViaName = term()
392 Module = atom()
393 Args = term()
394 Options = [Option]
395 Option = {debug,Dbgs} | {timeout,Time} | {hiber‐
396 nate_after,HibernateAfterTimeout} | {spawn_opt,SOpts}
397 Dbgs = [Dbg]
398 Dbg = trace | log | statistics | {log_to_file,FileName} |
399 {install,{Func,FuncState}}
400 SOpts = [term()]
401 Result = {ok,Pid} | ignore | {error,Error}
402 Pid = pid()
403 Error = {already_started,Pid} | term()
404 Creates a gen_server process as part of a supervision tree. This
406 function is to be called, directly or indirectly, by the super‐
407 visor. For example, it ensures that the gen_server process is
408 linked to the supervisor.
409 The gen_server process calls Module:init/1 to initialize. To
411 ensure a synchronized startup procedure, start_link/3,4 does not
412 return until Module:init/1 has returned.
413 * If ServerName={local,Name}, the gen_server process is regis‐
415 tered locally as Name using register/2.
416 * If ServerName={global,GlobalName}, the gen_server process id
418 registered globally as GlobalName using global:regis‐
419 ter_name/2 If no name is provided, the gen_server process is
420 not registered.
421 * If ServerName={via,Module,ViaName}, the gen_server process
423 registers with the registry represented by Module. The Mod‐
424 ule callback is to export the functions register_name/2,
425 unregister_name/1, whereis_name/1, and send/2, which are to
426 behave like the corresponding functions in global. Thus,
427 {via,global,GlobalName} is a valid reference.
428 Module is the name of the callback module.
430 Args is any term that is passed as the argument to Mod‐
432 ule:init/1.
433 * If option {timeout,Time} is present, the gen_server process
435 is allowed to spend Time milliseconds initializing or it is
436 terminated and the start function returns {error,timeout}.
437 * If option {hibernate_after,HibernateAfterTimeout} is
439 present, the gen_server process awaits any message for
440 HibernateAfterTimeout milliseconds and if no message is
441 received, the process goes into hibernation automatically
442 (by calling proc_lib:hibernate/3).
443 * If option {debug,Dbgs} is present, the corresponding sys
445 function is called for each item in Dbgs; see sys(3).
446 * If option {spawn_opt,SOpts} is present, SOpts is passed as
448 option list to the spawn_opt BIF, which is used to spawn the
449 gen_server process; see spawn_opt/2.
450 Note:
452 Using spawn option monitor is not allowed, it causes the func‐
453 tion to fail with reason badarg.
454 If the gen_server process is successfully created and initial‐
457 ized, the function returns {ok,Pid}, where Pid is the pid of the
458 gen_server process. If a process with the specified ServerName
459 exists already, the function returns
460 {error,{already_started,Pid}}, where Pid is the pid of that
461 process.
462 If Module:init/1 fails with Reason, the function returns
464 {error,Reason}. If Module:init/1 returns {stop,Reason} or
465 ignore, the process is terminated and the function returns
466 {error,Reason} or ignore, respectively.
467 start_monitor(Module, Args, Options) -> Result
469 start_monitor(ServerName, Module, Args, Options) -> Result
470 Types:
472 ServerName = {local,Name} | {global,GlobalName}
474 | {via,Module,ViaName}
475 Name = atom()
476 GlobalName = ViaName = term()
477 Module = atom()
478 Args = term()
479 Options = [Option]
480 Option = {debug,Dbgs} | {timeout,Time} | {hiber‐
481 nate_after,HibernateAfterTimeout} | {spawn_opt,SOpts}
482 Dbgs = [Dbg]
483 Dbg = trace | log | statistics | {log_to_file,FileName} |
484 {install,{Func,FuncState}}
485 SOpts = [term()]
486 Result = {ok,{Pid,Mon}} | ignore | {error,Error}
487 Pid = pid()
488 Error = {already_started,Pid} | term()
489 Creates a standalone gen_server process, that is, a gen_server
491 process that is not part of a supervision tree (and thus has no
492 supervisor) and atomically sets up a monitor to the newly cre‐
493 ated server.
494 For a description of arguments and return values, see
496 start_link/3,4. Note that the return value on successful start
497 differs from start_link/3,4. start_monitor/3,4 will return
498 {ok,{Pid,Mon}} where Pid is the process identifier of the
499 server, and Mon is a reference to the monitor set up to monitor
500 the server. If the start is not successful, the caller will be
501 blocked until the DOWN message has been received and removed
502 from the message queue.
503 stop(ServerRef) -> ok
505 stop(ServerRef, Reason, Timeout) -> ok
506 Types:
508 ServerRef = Name | {Name,Node} | {global,GlobalName}
510 | {via,Module,ViaName} | pid()
511 Node = atom()
512 GlobalName = ViaName = term()
513 Reason = term()
514 Timeout = int()>0 | infinity
515 Orders a generic server to exit with the specified Reason and
517 waits for it to terminate. The gen_server process calls Mod‐
518 ule:terminate/2 before exiting.
519 The function returns ok if the server terminates with the
521 expected reason. Any other reason than normal, shutdown, or
522 {shutdown,Term} causes an error report to be issued using log‐
523 ger(3). The default Reason is normal.
524 Timeout is an integer greater than zero that specifies how many
526 milliseconds to wait for the server to terminate, or the atom
527 infinity to wait indefinitely. Defaults to infinity. If the
528 server has not terminated within the specified time, a timeout
529 exception is raised.
530 If the process does not exist, a noproc exception is raised.
532 wait_response(RequestId, Timeout) -> Result
534 Types:
536 RequestId = term()
538 Result = {reply, Reply} | timeout | {error, {Reason, Server‐
539 Ref}}
540 Reply = term()
541 Timeout = timeout()
542 Reason = term()
543 ServerRef = Name | {Name,Node} | {global,GlobalName}
544 | {via,Module,ViaName} | pid()
545 Node = atom()
546 GlobalName = ViaName = term()
547 This function is used to wait for a reply of a request made with
549 send_request/2 from the gen_server process. This function must
550 be called from the same process from which send_request/2 was
551 made.
552 Timeout is an integer greater then or equal to zero that speci‐
554 fies how many milliseconds to wait for an reply, or the atom
555 infinity to wait indefinitely. If no reply is received within
556 the specified time, the function returns timeout and no cleanup
557 is done, and thus the function can be invoked repeatedly until a
558 reply is returned.
559 The return value Reply is defined in the return value of Mod‐
561 ule:handle_call/3.
562 The function returns an error if the gen_server dies before or
564 during this request.
565
567 The following functions are to be exported from a gen_server callback
568 module.
569
571 Module:code_change(OldVsn, State, Extra) -> {ok, NewState} | {error,
572 Reason}
573 Types:
575 OldVsn = Vsn | {down, Vsn}
577 Vsn = term()
578 State = NewState = term()
579 Extra = term()
580 Reason = term()
581 Note:
583 This callback is optional, so callback modules need not export
584 it. If a release upgrade/downgrade with Change={advanced,Extra}
585 specified in the appup file is made when code_change/3 isn't
586 implemented the process will crash with an undef exit reason.
587 This function is called by a gen_server process when it is to
590 update its internal state during a release upgrade/downgrade,
591 that is, when the instruction {update,Module,Change,...}, where
592 Change={advanced,Extra}, is specifed in the appup file. For more
593 information, see section Release Handling Instructions in OTP
594 Design Principles.
595 For an upgrade, OldVsn is Vsn, and for a downgrade, OldVsn is
597 {down,Vsn}. Vsn is defined by the vsn attribute(s) of the old
598 version of the callback module Module. If no such attribute is
599 defined, the version is the checksum of the Beam file.
600 State is the internal state of the gen_server process.
602 Extra is passed "as is" from the {advanced,Extra} part of the
604 update instruction.
605 If successful, the function must return the updated internal
607 state.
608 If the function returns {error,Reason}, the ongoing upgrade
610 fails and rolls back to the old release.
611 Module:format_status(Opt, [PDict, State]) -> Status
613 Types:
615 Opt = normal | terminate
617 PDict = [{Key, Value}]
618 State = term()
619 Status = term()
620 Note:
622 This callback is optional, so callback modules need not export
623 it. The gen_server module provides a default implementation of
624 this function that returns the callback module state.
625 This function is called by a gen_server process in the following
628 situations:
629 * One of sys:get_status/1,2 is invoked to get the gen_server
631 status. Opt is set to the atom normal.
632 * The gen_server process terminates abnormally and logs an
634 error. Opt is set to the atom terminate.
635 This function is useful for changing the form and appearance of
637 the gen_server status for these cases. A callback module wishing
638 to change the sys:get_status/1,2 return value, as well as how
639 its status appears in termination error logs, exports an
640 instance of format_status/2 that returns a term describing the
641 current status of the gen_server process.
642 PDict is the current value of the process dictionary of the
644 gen_server process..
645 State is the internal state of the gen_server process.
647 The function is to return Status, a term that changes the
649 details of the current state and status of the gen_server
650 process. There are no restrictions on the form Status can take,
651 but for the sys:get_status/1,2 case (when Opt is normal), the
652 recommended form for the Status value is [{data, [{"State",
653 Term}]}], where Term provides relevant details of the gen_server
654 state. Following this recommendation is not required, but it
655 makes the callback module status consistent with the rest of the
656 sys:get_status/1,2 return value.
657 One use for this function is to return compact alternative state
659 representations to avoid that large state terms are printed in
660 log files.
661 Module:handle_call(Request, From, State) -> Result
663 Types:
665 Request = term()
667 From = {pid(),Tag}
668 State = term()
669 Result = {reply,Reply,NewState} | {reply,Reply,NewState,Time‐
670 out}
671 | {reply,Reply,NewState,hibernate}
672 | {reply,Reply,NewState,{continue,Continue}}
673 | {noreply,NewState} | {noreply,NewState,Timeout}
674 | {noreply,NewState,hibernate}
675 | {noreply,NewState,{continue,Continue}}
676 | {stop,Reason,Reply,NewState} | {stop,Reason,NewState}
677 Reply = term()
678 NewState = term()
679 Timeout = int()>=0 | infinity
680 Continue = term()
681 Reason = term()
682 Whenever a gen_server process receives a request sent using
684 call/2,3 or multi_call/2,3,4, this function is called to handle
685 the request.
686 Request is the Request argument provided to call or multi_call.
688 From is a tuple {Pid,Tag}, where Pid is the pid of the client
690 and Tag is a unique tag.
691 State is the internal state of the gen_server process.
693 * If {reply,Reply,NewState} is returned, {reply,Reply,New‐
695 State,Timeout} or {reply,Reply,NewState,hibernate}, Reply is
696 given back to From as the return value of call/2,3 or
697 included in the return value of multi_call/2,3,4. The
698 gen_server process then continues executing with the possi‐
699 bly updated internal state NewState.
700 For a description of Timeout and hibernate, see Mod‐
702 ule:init/1.
703 * If {noreply,NewState} is returned, {noreply,NewState,Time‐
705 out}, or {noreply,NewState,hibernate}, the gen_server
706 process continues executing with NewState. Any reply to From
707 must be specified explicitly using reply/2.
708 * If {stop,Reason,Reply,NewState} is returned, Reply is given
710 back to From.
711 * If {stop,Reason,NewState} is returned, any reply to From
713 must be specified explicitly using reply/2. The gen_server
714 process then calls Module:terminate(Reason,NewState) and
715 terminates.
716 Module:handle_cast(Request, State) -> Result
718 Types:
720 Request = term()
722 State = term()
723 Result = {noreply,NewState} | {noreply,NewState,Timeout}
724 | {noreply,NewState,hibernate}
725 | {noreply,NewState,{continue,Continue}}
726 | {stop,Reason,NewState}
727 NewState = term()
728 Timeout = int()>=0 | infinity
729 Continue = term()
730 Reason = term()
731 Whenever a gen_server process receives a request sent using
733 cast/2 or abcast/2,3, this function is called to handle the
734 request.
735 For a description of the arguments and possible return values,
737 see Module:handle_call/3.
738 Module:handle_continue(Continue, State) -> Result
740 Types:
742 Continue = term()
744 State = term()
745 Result = {noreply,NewState} | {noreply,NewState,Timeout}
746 | {noreply,NewState,hibernate}
747 | {noreply,NewState,{continue,Continue}}
748 | {stop,Reason,NewState}
749 NewState = term()
750 Timeout = int()>=0 | infinity
751 Continue = term()
752 Reason = normal | term()
753 Note:
755 This callback is optional, so callback modules need to export it
756 only if they return {continue,Continue} from another callback.
757 If continue is used and the callback is not implemented, the
758 process will exit with undef error.
759 This function is called by a gen_server process whenever a pre‐
762 vious callback returns {continue, Continue}. handle_continue/2
763 is invoked immediately after the previous callback, which makes
764 it useful for performing work after initialization or for split‐
765 ting the work in a callback in multiple steps, updating the
766 process state along the way.
767 For a description of the other arguments and possible return
769 values, see Module:handle_call/3.
770 Module:handle_info(Info, State) -> Result
772 Types:
774 Info = timeout | term()
776 State = term()
777 Result = {noreply,NewState} | {noreply,NewState,Timeout}
778 | {noreply,NewState,hibernate}
779 | {noreply,NewState,{continue,Continue}}
780 | {stop,Reason,NewState}
781 NewState = term()
782 Timeout = int()>=0 | infinity
783 Reason = normal | term()
784 Note:
786 This callback is optional, so callback modules need not export
787 it. The gen_server module provides a default implementation of
788 this function that logs about the unexpected Info message, drops
789 it and returns {noreply, State}.
790 This function is called by a gen_server process when a time-out
793 occurs or when it receives any other message than a synchronous
794 or asynchronous request (or a system message).
795 Info is either the atom timeout, if a time-out has occurred, or
797 the received message.
798 For a description of the other arguments and possible return
800 values, see Module:handle_call/3.
801 Module:init(Args) -> Result
803 Types:
805 Args = term()
807 Result = {ok,State} | {ok,State,Timeout} | {ok,State,hiber‐
808 nate}
809 | {ok,State,{continue,Continue}} | {stop,Reason} | ignore
810 State = term()
811 Timeout = int()>=0 | infinity
812 Reason = term()
813 Whenever a gen_server process is started using start/3,4,
815 start_monitor/3,4, or start_link/3,4, this function is called by
816 the new process to initialize.
817 Args is the Args argument provided to the start function.
819 If the initialization is successful, the function is to return
821 {ok,State}, {ok,State,Timeout}, or {ok,State,hibernate}, where
822 State is the internal state of the gen_server process.
823 If an integer time-out value is provided, a time-out occurs
825 unless a request or a message is received within Timeout mil‐
826 liseconds. A time-out is represented by the atom timeout, which
827 is to be handled by the Module:handle_info/2 callback function.
828 The atom infinity can be used to wait indefinitely, this is the
829 default value.
830 If hibernate is specified instead of a time-out value, the
832 process goes into hibernation when waiting for the next message
833 to arrive (by calling proc_lib:hibernate/3).
834 If the initialization fails, the function is to return
836 {stop,Reason}, where Reason is any term, or ignore.
837 Module:terminate(Reason, State)
839 Types:
841 Reason = normal | shutdown | {shutdown,term()} | term()
843 State = term()
844 Note:
846 This callback is optional, so callback modules need not export
847 it. The gen_server module provides a default implementation
848 without cleanup.
849 This function is called by a gen_server process when it is about
852 to terminate. It is to be the opposite of Module:init/1 and do
853 any necessary cleaning up. When it returns, the gen_server
854 process terminates with Reason. The return value is ignored.
855 Reason is a term denoting the stop reason and State is the
857 internal state of the gen_server process.
858 Reason depends on why the gen_server process is terminating. If
860 it is because another callback function has returned a stop
861 tuple {stop,..}, Reason has the value specified in that tuple.
862 If it is because of a failure, Reason is the error reason.
863 If the gen_server process is part of a supervision tree and is
865 ordered by its supervisor to terminate, this function is called
866 with Reason=shutdown if the following conditions apply:
867 * The gen_server process has been set to trap exit signals.
869 * The shutdown strategy as defined in the child specification
871 of the supervisor is an integer time-out value, not bru‐
872 tal_kill.
873 Even if the gen_server process is not part of a supervision
875 tree, this function is called if it receives an 'EXIT' message
876 from its parent. Reason is the same as in the 'EXIT' message.
877 Otherwise, the gen_server process terminates immediately.
879 Notice that for any other reason than normal, shutdown, or
881 {shutdown,Term}, the gen_server process is assumed to terminate
882 because of an error and an error report is issued using log‐
883 ger(3).
884
886 gen_event(3), gen_statem(3), proc_lib(3), supervisor(3), sys(3)
887Ericsson AB stdlib 3.14.1 gen_server(3)