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_link -----> Module:init/1
25 gen_server:stop -----> Module:terminate/2
27 gen_server:call
29 gen_server:multi_call -----> Module:handle_call/3
30 gen_server:cast
32 gen_server:abcast -----> Module:handle_cast/2
33 - -----> Module:handle_info/2
35 - -----> Module:handle_continue/2
37 - -----> Module:terminate/2
39 - -----> Module:code_change/3
41 If a callback function fails or returns a bad value, the gen_server
43 process terminates.
44 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 Notice that a gen_server process does not trap exit signals automati‐
49 cally, this must be explicitly initiated in the callback module.
50 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 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 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
70 abcast(Name, Request) -> abcast
71 abcast(Nodes, Name, Request) -> abcast
72 Types:
74 Nodes = [Node]
76 Node = atom()
77 Name = atom()
78 Request = term()
79 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 For a description of the arguments, see multi_call/2,3,4.
87 call(ServerRef, Request) -> Reply
89 call(ServerRef, Request, Timeout) -> Reply
90 Types:
92 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 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 ServerRef can be any of the following:
107 * The pid
109 * Name, if the gen_server process is locally registered
111 * {Name,Node}, if the gen_server process is locally registered
113 at another node
114 * {global,GlobalName}, if the gen_server process is globally
116 registered
117 * {via,Module,ViaName}, if the gen_server process is regis‐
119 tered through an alternative process registry
120 Request is any term that is passed as one of the arguments to
122 Module:handle_call/3.
123 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 The return value Reply is defined in the return value of Mod‐
135 ule:handle_call/3.
136 The call can fail for many reasons, including time-out and the
138 called gen_server process dying before or during the call.
139 cast(ServerRef, Request) -> ok
141 Types:
143 ServerRef = Name | {Name,Node} | {global,GlobalName}
145 | {via,Module,ViaName} | pid()
146 Node = atom()
147 GlobalName = ViaName = term()
148 Request = term()
149 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 For a description of ServerRef, see call/2,3.
156 Request is any term that is passed as one of the arguments to
158 Module:handle_cast/2.
159 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 Types:
166 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 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 This function is useful when a more complex initialization pro‐
189 cedure is needed than the gen_server process behavior provides.
190 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 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 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 multi_call(Name, Request) -> Result
205 multi_call(Nodes, Name, Request) -> Result
206 multi_call(Nodes, Name, Request, Timeout) -> Result
207 Types:
209 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 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 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 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 Name is the locally registered name of each gen_server process.
236 Request is any term that is passed as one of the arguments to
238 Module:handle_call/3.
239 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 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 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 This problem does not exist if all nodes are Erlang nodes.
257 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 reply(Client, Reply) -> Result
265 Types:
267 Client - see below
269 Reply = term()
270 Result = term()
271 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 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 The return value Result is not further defined, and is always to
282 be ignored.
283 start(Module, Args, Options) -> Result
285 start(ServerName, Module, Args, Options) -> Result
286 Types:
288 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 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 For a description of arguments and return values, see
311 start_link/3,4.
312 start_link(Module, Args, Options) -> Result
314 start_link(ServerName, Module, Args, Options) -> Result
315 Types:
317 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 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 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 * If ServerName={local,Name}, the gen_server process is regis‐
345 tered locally as Name using register/2.
346 * 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 * 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 Module is the name of the callback module.
360 Args is any term that is passed as the argument to Mod‐
362 ule:init/1.
363 * 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 * 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 * If option {debug,Dbgs} is present, the corresponding sys
375 function is called for each item in Dbgs; see sys(3).
376 * 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 Note:
382 Using spawn option monitor is not allowed, it causes the func‐
383 tion to fail with reason badarg.
384 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 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 stop(ServerRef) -> ok
399 stop(ServerRef, Reason, Timeout) -> ok
400 Types:
402 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 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 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 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 If the process does not exist, a noproc exception is raised.
426
428 The following functions are to be exported from a gen_server callback
429 module.
430
432 Module:code_change(OldVsn, State, Extra) -> {ok, NewState} | {error,
433 Reason}
434 Types:
436 OldVsn = Vsn | {down, Vsn}
438 Vsn = term()
439 State = NewState = term()
440 Extra = term()
441 Reason = term()
442 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 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 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 State is the internal state of the gen_server process.
463 Extra is passed "as is" from the {advanced,Extra} part of the
465 update instruction.
466 If successful, the function must return the updated internal
468 state.
469 If the function returns {error,Reason}, the ongoing upgrade
471 fails and rolls back to the old release.
472 Module:format_status(Opt, [PDict, State]) -> Status
474 Types:
476 Opt = normal | terminate
478 PDict = [{Key, Value}]
479 State = term()
480 Status = term()
481 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 This function is called by a gen_server process in the following
489 situations:
490 * One of sys:get_status/1,2 is invoked to get the gen_server
492 status. Opt is set to the atom normal.
493 * The gen_server process terminates abnormally and logs an
495 error. Opt is set to the atom terminate.
496 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 PDict is the current value of the process dictionary of the
505 gen_server process..
506 State is the internal state of the gen_server process.
508 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 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 Module:handle_call(Request, From, State) -> Result
524 Types:
526 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 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 Request is the Request argument provided to call or multi_call.
549 From is a tuple {Pid,Tag}, where Pid is the pid of the client
551 and Tag is a unique tag.
552 State is the internal state of the gen_server process.
554 * 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 For a description of Timeout and hibernate, see Mod‐
563 ule:init/1.
564 * 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 * If {stop,Reason,Reply,NewState} is returned, Reply is given
571 back to From.
572 * 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 Module:handle_cast(Request, State) -> Result
579 Types:
581 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 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 For a description of the arguments and possible return values,
598 see Module:handle_call/3.
599 Module:handle_continue(Continue, State) -> Result
601 Types:
603 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 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 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 For a description of the other arguments and possible return
630 values, see Module:handle_call/3.
631 Module:handle_info(Info, State) -> Result
633 Types:
635 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 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 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 Info is either the atom timeout, if a time-out has occurred, or
658 the received message.
659 For a description of the other arguments and possible return
661 values, see Module:handle_call/3.
662 Module:init(Args) -> Result
664 Types:
666 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 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 Args is the Args argument provided to the start function.
680 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 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 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 If the initialization fails, the function is to return
697 {stop,Reason}, where Reason is any term, or ignore.
698 Module:terminate(Reason, State)
700 Types:
702 Reason = normal | shutdown | {shutdown,term()} | term()
704 State = term()
705 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 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 Reason is a term denoting the stop reason and State is the
718 internal state of the gen_server process.
719 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 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 * The gen_server process has been set to trap exit signals.
730 * 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 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 Otherwise, the gen_server process terminates immediately.
740 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
747 gen_event(3), gen_statem(3), proc_lib(3), supervisor(3), sys(3)
748Ericsson AB stdlib 3.10 gen_server(3)