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 If the gen_server process terminates, e.g. as a result of a function in
72 the callback module returning {stop,Reason,NewState}, an exit signal
73 with this Reason is sent to linked processes and ports. See Processes
74 in the Reference Manual for details regarding error handling using exit
75 signals.
76
78 server_name() =
79 {local, LocalName :: atom()} |
80 {global, GlobalName :: term()} |
81 {via, RegMod :: module(), ViaName :: term()}
82 Name specification to use when starting a gen_server. See func‐
84 tions start/3,4, start_link/3,4, start_monitor/3,4, en‐
85 ter_loop/3,4,5, and the type server_ref() below.
86 {local,LocalName}:
88 Register the gen_server locally as LocalName using regis‐
89 ter/2.
90 {global,GlobalName}:
92 Register the gen_server process id globally as GlobalName
93 using global:register_name/2.
94 {via,RegMod,ViaName}:
96 Register the gen_server process with the registry repre‐
97 sented by RegMod. The RegMod callback is to export the func‐
98 tions register_name/2, unregister_name/1, whereis_name/1,
99 and send/2, which are to behave like the corresponding func‐
100 tions in global. Thus, {via,global,GlobalName} is a valid
101 reference equivalent to {global,GlobalName}.
102 server_ref() =
104 pid() |
105 (LocalName :: atom()) |
106 {Name :: atom(), Node :: atom()} |
107 {global, GlobalName :: term()} |
108 {via, RegMod :: module(), ViaName :: term()}
109 Server specification to use when addressing a gen_server. See
111 call/2,3, cast/2, send_request/2, check_response/2, wait_re‐
112 sponse/2, stop/2,3 and the type server_name() above.
113 It can be:
115 pid():
117 The gen_server's process identifier.
118 LocalName:
120 The gen_server is locally registered as LocalName with reg‐
121 ister/2.
122 {Name,Node}:
124 The gen_server is locally registered on another node.
125 {global,GlobalName}:
127 The gen_server is globally registered in global.
128 {via,RegMod,ViaName}:
130 The gen_server is registered in an alternative process reg‐
131 istry. The registry callback module RegMod is to export
132 functions register_name/2, unregister_name/1,
133 whereis_name/1, and send/2, which are to behave like the
134 corresponding functions in global. Thus, {via,global,Global‐
135 Name} is the same as {global,GlobalName}.
136 start_opt() =
138 {timeout, Timeout :: timeout()} |
139 {spawn_opt, SpawnOptions :: [proc_lib:spawn_option()]} |
140 enter_loop_opt()
141 Options that can be used when starting a gen_server server
143 through, for example, start_link/3,4.
144 {timeout,Timeout}:
146 How many milliseconds the gen_server process is allowed to
147 spend initializing or it is terminated and the start func‐
148 tion returns {error,timeout}.
149 {spawn_opt,SpawnOptions}:
151 The SpawnOptions option list is passed to the function used
152 to spawn the gen_server; see spawn_opt/2.
153 Note:
155 Using spawn option monitor is not allowed, it causes a badarg
156 failure.
157 enter_loop_opt():
160 See the type enter_loop_opt() below for more start options
161 that are also allowed by enter_loop/3,4,5.
162 enter_loop_opt() =
164 {hibernate_after, HibernateAfterTimeout :: timeout()} |
165 {debug, Dbgs :: [sys:debug_option()]}
166 Options that can be used when starting a gen_server server
168 through enter_loop/3-5 or the start functions such as
169 start_link/3,4.
170 {hibernate_after,HibernateAfterTimeout}:
172 Specifies that the gen_server process awaits any message for
173 HibernateAfterTimeout milliseconds and if no message is re‐
174 ceived, the process goes into hibernation automatically (by
175 calling proc_lib:hibernate/3).
176 {debug,Dbgs}:
178 For every entry in Dbgs, the corresponding function in
179 sys(3) is called.
180 start_ret() =
182 {ok, Pid :: pid()} | ignore | {error, Reason :: term()}
183 Return value from the start/3,4 and start_link/3,4 functions.
185 {ok,Pid}:
187 The gen_server process was succesfully created and initial‐
188 ized, with the process identifier Pid.
189 {error,{already_started,OtherPid}}:
191 A process with the specified ServerName exists already with
192 the process identifier OtherPid. This gen_server was not
193 started.
194 ignore:
196 Module:init/1 returned ignore, the gen_server process is
197 terminated. An exit signal normal is sent to linked pro‐
198 cesses and ports.
199 {error,Reason}:
201 Module:init/1 returned {stop,Reason} or failed with Reason.
202 The gen_server process is terminated and an exit signal with
203 the same Reason is sent to linked processes and ports.
204 start_mon_ret() =
206 {ok, {Pid :: pid(), MonRef :: reference()}} |
207 ignore |
208 {error, Reason :: term()}
209 Return value from the start_monitor/3,4 functions. The same as
211 type start_ret() except that for a succesful start it returns
212 both the process identifier Pid and a monitor/2,3 reference()
213 MonRef.
214 from() = {Client :: pid(), Tag :: reply_tag()}
216 Destination, given to the gen_server as the first argument to
218 the callback function Module:handle_call/3, to be used by the
219 when replying through reply/2 (instead of through the callback
220 function's return value) to the process Client that has called
221 the gen_server using call/2,3. Tag is a term that is unique for
222 this call/request instance.
223 reply_tag()
225 A handle that associates a reply to the corresponding request.
227 request_id()
229 An opaque request identifier. See send_request/2 for details.
231 request_id_collection()
233 An opaque collection of request identifiers (request_id()) where
235 each request identifier can be associated with a label chosen by
236 the user. For more information see reqids_new/0.
237 response_timeout() = timeout() | {abs, integer()}
239 Used to set a time limit on how long to wait for a response us‐
241 ing either receive_response/2, receive_response/3, wait_re‐
242 sponse/2, or wait_response/3. The time unit used is millisecond.
243 Currently valid values:
244 0..4294967295:
246 Timeout relative to current time in milliseconds.
247 infinity:
249 Infinite timeout. That is, the operation will never time
250 out.
251 {abs, Timeout}:
253 An absolute Erlang monotonic time timeout in milliseconds.
254 That is, the operation will time out when erlang:mono‐
255 tonic_time(millisecond) returns a value larger than or equal
256 to Timeout. Timeout is not allowed to identify a time fur‐
257 ther into the future than 4294967295 milliseconds. Identify‐
258 ing the timeout using an absolute timeout value is espe‐
259 cially handy when you have a deadline for responses corre‐
260 sponding to a complete collection of requests (re‐
261 quest_id_collection()) , since you do not have to recalcu‐
262 late the relative time until the deadline over and over
263 again.
264 format_status() =
266 #{state => term(),
267 message => term(),
268 reason => term(),
269 log => [sys:system_event()]}
270 A map that describes the gen_server status. The keys are:
272 state:
274 The internal state of the gen_server process.
275 message:
277 The message that caused the server to terminate.
278 reason:
280 The reason that caused the server to terminate.
281 log:
283 The sys log of the server.
284 New associations may be added to the status map without prior
286 notice.
287
289 abcast(Name :: atom(), Request :: term()) -> abcast
290 abcast(Nodes :: [node()], Name :: atom(), Request :: term()) ->
292 abcast
293 Sends an asynchronous request to the gen_server processes lo‐
295 cally registered as Name at the specified nodes. The function
296 returns immediately and ignores nodes that do not exist, or
297 where the gen_server Name does not exist. The gen_server pro‐
298 cesses call Module:handle_cast/2 to handle the request.
299 For a description of the arguments, see multi_call/2,3,4.
301 call(ServerRef :: server_ref(), Request :: term()) ->
303 Reply :: term()
304 call(ServerRef :: server_ref(),
306 Request :: term(),
307 Timeout :: timeout()) ->
308 Reply :: term()
309 Makes a synchronous call to the ServerRef of the gen_server
311 process by sending a request and waiting until a reply arrives
312 or a time-out occurs. The gen_server process calls Module:han‐
313 dle_call/3 to handle the request.
314 See also ServerRef's type server_ref().
316 Request is any term that is passed as the first argument to Mod‐
318 ule:handle_call/3.
319 Timeout is an integer that specifies how many milliseconds to
321 wait for a reply, or the atom infinity to wait indefinitely. De‐
322 faults to 5000. If no reply is received within the specified
323 time, this function exits the calling process with an exit term
324 containing Reason = timeout as described below.
325 Note:
327 Before OTP 24, if the caller uses (try...)catch to avoid process
328 exit, and the server happens to just be late with the reply, it
329 may arrive to the process message queue any time later. The
330 calling process must therefore after catching a time-out exit be
331 prepared to receive garbage message(s) on the form {reference(),
332 _} and deal with them appropriately (discard them) so they do
333 not clog the process message queue or gets mistaken for other
334 messages.
335 Starting with OTP 24, gen_server:call uses process aliases, so
337 late replies will not be received.
338 The return value Reply is passed from the return value of Mod‐
341 ule:handle_call/3.
342 This call may exit the calling process with an exit term on the
344 form {Reason, Location} where Location = {gen_server,call,Ar‐
345 gList} and Reason can be (at least) one of:
346 timeout:
348 The call was aborted after waiting Timeout milliseconds for
349 a reply, as described above.
350 noproc:
352 The ServerRef refers to a server by name (it is not a pid())
353 and looking up the server process failed, or the pid() was
354 already terminated.
355 {nodedown,Node}:
357 The ServerRef refers to a server on the remote node Node and
358 the connection to that node failed.
359 calling_self:
361 A call to self() would hang indefinitely.
362 shutdown
364 : The server was stopped during the call by its supervisor.
365 See also stop/3.
366 normal
368 {shutdown,Term}
369 : The server stopped during the call by returning {stop,Rea‐
370 son,_} from its Module:handle_call/3 callback, without re‐
371 plying. See also stop/3.
372 _OtherTerm:
374 The server process exited during the call, with reason Rea‐
375 son. Either by returning {stop,Reason,_} from its Mod‐
376 ule:handle_call/3 callback (without replying), by raising an
377 exception, or due to getting an exit signal it did not trap.
378 cast(ServerRef :: server_ref(), Request :: term()) -> ok
380 Sends an asynchronous request to the ServerRef of the gen_server
382 process and returns ok immediately, ignoring if the destination
383 node or gen_server process does not exist. The gen_server
384 process calls Module:handle_cast/2 to handle the request.
385 See also ServerRef's type server_ref().
387 Request is any term that is passed as the first argument to Mod‐
389 ule:handle_cast/2.
390 check_response(Msg, ReqId) -> Result
392 Types:
394 Msg = term()
396 ReqId = request_id()
397 Response =
398 {reply, Reply :: term()} |
399 {error, {Reason :: term(), server_ref()}}
400 Result = Response | no_reply
401 Check if Msg is a response corresponding to the request identi‐
403 fier ReqId. The request must have been made by send_request/2,
404 and it must have been made by the same process calling this
405 function.
406 If Msg is a response corresponding to ReqId the response is re‐
408 turned; otherwise, no_reply is returned and no cleanup is done,
409 and thus the function must be invoked repeatedly until a re‐
410 sponse is returned.
411 The return value Reply is passed from the return value of Mod‐
413 ule:handle_call/3.
414 The function returns an error if the gen_server died before a
416 reply was sent.
417 check_response(Msg, ReqIdCollection, Delete) -> Result
419 Types:
421 Msg = term()
423 ReqIdCollection = request_id_collection()
424 Delete = boolean()
425 Response =
426 {reply, Reply :: term()} |
427 {error, {Reason :: term(), server_ref()}}
428 Result =
429 {Response,
430 Label :: term(),
431 NewReqIdCollection :: request_id_collection()} |
432 no_request | no_reply
433 Check if Msg is a response corresponding to a request identifier
435 saved in ReqIdCollection. All request identifiers of ReqIdCol‐
436 lection must correspond to requests that have been made using
437 send_request/2 or send_request/4, and all request must have been
438 made by the process calling this function.
439 The Label in the response equals the Label associated with the
441 request identifier that the response corresponds to. The Label
442 of a request identifier is associated when saving the request id
443 in a request identifier collection, or when sending the request
444 using send_request/4.
445 Compared to check_response/2, the returned result associated
447 with a specific request identifier or an exception associated
448 with a specific request identifier will be wrapped in a 3-tuple.
449 The first element of this tuple equals the value that would have
450 been produced by check_response/2, the second element equals the
451 Label associated with the specific request identifier, and the
452 third element NewReqIdCollection is a possibly modified request
453 identifier collection.
454 If ReqIdCollection is empty, the atom no_request will be re‐
456 turned. If Msg does not correspond to any of the request identi‐
457 fiers in ReqIdCollection, the atom no_reply is returned.
458 If Delete equals true, the association with Label will have been
460 deleted from ReqIdCollection in the resulting NewReqIdCollec‐
461 tion. If Delete equals false, NewReqIdCollection will equal Re‐
462 qIdCollection. Note that deleting an association is not for free
463 and that a collection containing already handled requests can
464 still be used by subsequent calls to check_response/3, re‐
465 ceive_response/3, and wait_response/3. However, without deleting
466 handled associations, the above calls will not be able to detect
467 when there are no more outstanding requests to handle, so you
468 will have to keep track of this some other way than relying on a
469 no_request return. Note that if you pass a collection only con‐
470 taining associations of already handled or abandoned requests to
471 check_response/3, it will always return no_reply.
472 enter_loop(Module :: module(),
474 Options :: [enter_loop_opt()],
475 State :: term()) ->
476 no_return()
477 enter_loop(Module :: module(),
479 Options :: [enter_loop_opt()],
480 State :: term(),
481 ServerName :: server_name() | pid()) ->
482 no_return()
483 enter_loop(Module :: module(),
485 Options :: [enter_loop_opt()],
486 State :: term(),
487 Timeout :: timeout()) ->
488 no_return()
489 enter_loop(Module :: module(),
491 Options :: [enter_loop_opt()],
492 State :: term(),
493 Hibernate :: hibernate) ->
494 no_return()
495 enter_loop(Module :: module(),
497 Options :: [enter_loop_opt()],
498 State :: term(),
499 Cont :: {continue, term()}) ->
500 no_return()
501 enter_loop(Module :: module(),
503 Options :: [enter_loop_opt()],
504 State :: term(),
505 ServerName :: server_name() | pid(),
506 Timeout :: timeout()) ->
507 no_return()
508 enter_loop(Module :: module(),
510 Options :: [enter_loop_opt()],
511 State :: term(),
512 ServerName :: server_name() | pid(),
513 Hibernate :: hibernate) ->
514 no_return()
515 enter_loop(Module :: module(),
517 Options :: [enter_loop_opt()],
518 State :: term(),
519 ServerName :: server_name() | pid(),
520 Cont :: {continue, term()}) ->
521 no_return()
522 Makes an existing process a gen_server process. Does not return,
524 instead the calling process enters the gen_server process re‐
525 ceive loop and becomes a gen_server process. The process must
526 have been started using one of the start functions in
527 proc_lib(3). The user is responsible for any initialization of
528 the process, including registering a name for it.
529 This function is useful when a more complex initialization pro‐
531 cedure is needed than the gen_server process behavior provides.
532 Module, Options, and ServerName have the same meanings as when
534 calling start[_link|_monitor]/3,4 or it can be self() for an
535 anonymous server, which is the same as calling an enter_loop/3,4
536 function without a ServerName argument. However, if ServerName
537 is specified (and not as self()), the process must have been
538 registered accordingly before this function is called.
539 State, Timeout, Hibernate and Cont have the same meanings as in
541 the return value of Module:init/1, which is not called when en‐
542 ter_loop/3,4,5 is used. Note that to adhere to the gen_server
543 Behaviour such a callback function needs to be defined, and it
544 might as well be the one used when starting the gen_server
545 process through proc_lib, and then be the one that calls en‐
546 ter_loop/3,4,5. But if such a Module:init/1 function in for ex‐
547 ample error cases cannot call enter_loop/3,4,5, it should return
548 a value that follows the type specification for Module:init/1
549 such as ignore, although that value will be lost when returning
550 to the spawning function.
551 This function fails if the calling process was not started by a
553 proc_lib start function, or if it is not registered according to
554 ServerName.
555 multi_call(Name :: atom(), Request :: term()) ->
557 {Replies :: [{Node :: node(), Reply :: term()}],
558 BadNodes :: [node()]}
559 multi_call(Nodes :: [node()], Name :: atom(), Request :: term()) ->
561 {Replies :: [{Node :: node(), Reply :: term()}],
562 BadNodes :: [node()]}
563 multi_call(Nodes :: [node()],
565 Name :: atom(),
566 Request :: term(),
567 Timeout :: timeout()) ->
568 {Replies :: [{Node :: node(), Reply :: term()}],
569 BadNodes :: [node()]}
570 Makes a synchronous call to all gen_server processes locally
572 registered as Name at the specified nodes, by first sending the
573 request to the nodes, and then waiting for the replies. The
574 gen_server processes on the nodes call Module:handle_call/3 to
575 handle the request.
576 The function returns a tuple {Replies,BadNodes}, where Replies
578 is a list of {Node,Reply} tuples, and BadNodes is a list of
579 nodes that either did not exist, where Name was not a registered
580 gen_server, or where it did not reply.
581 Nodes is a list of node names to which the request is to be
583 sent. Default value is the list of all known nodes
584 [node()|nodes()].
585 Name is the locally registered name for each gen_server process.
587 Request is any term that is passed as the first argument to Mod‐
589 ule:handle_call/3.
590 Timeout is an integer that specifies how many milliseconds to
592 wait for all replies, or the atom infinity to wait indefinitely,
593 which is the default. If no reply is received from a node within
594 the specified time, the node is added to BadNodes.
595 When a reply Reply is received from the gen_server process at a
597 node Node, {Node,Reply} is added to Replies. Reply is passed
598 from the return value of Module:handle_call/3.
599 Warning:
601 If one of the nodes cannot process monitors, for example, C or
602 Java nodes, and the gen_server process is not started when the
603 requests are sent, but starts within 2 seconds, this function
604 waits the whole Timeout, which may be infinity.
605 This problem does not exist if all nodes are Erlang nodes.
607 To prevent late answers (after the time-out) from polluting the
610 message queue of the caller, a middleman process is used to do
611 the calls. Late answers are then discarded when they arrive to a
612 terminated process.
613 receive_response(ReqId, Timeout) -> Result
615 Types:
617 ReqId = request_id()
619 Timeout = response_timeout()
620 Response =
621 {reply, Reply :: term()} |
622 {error, {Reason :: term(), server_ref()}}
623 Result = Response | timeout
624 Receive a response corresponding to the request identifier Re‐
626 qId. The request must have been made by send_request/2, and it
627 must have been made by the same process calling this function.
628 Timeout specifies how long to wait for a response. If no re‐
630 sponse is received within the specified time, the function re‐
631 turns timeout. Assuming that the server executes on a node sup‐
632 porting aliases (introduced in OTP 24) the request will also be
633 abandoned. That is, no response will be received after a time‐
634 out. Otherwise, a stray response might be received at a later
635 time.
636 The return value Reply is passed from the return value of Mod‐
638 ule:handle_call/3.
639 The function returns an error if the gen_server died before a
641 reply was sent.
642 The difference between receive_response/2 and wait_response/2 is
644 that receive_response/2 abandons the request at timeout so that
645 a potential future response is ignored, while wait_response/2
646 does not.
647 receive_response(ReqIdCollection, Timeout, Delete) -> Result
649 Types:
651 ReqIdCollection = request_id_collection()
653 Timeout = response_timeout()
654 Delete = boolean()
655 Response =
656 {reply, Reply :: term()} |
657 {error, {Reason :: term(), server_ref()}}
658 Result =
659 {Response,
660 Label :: term(),
661 NewReqIdCollection :: request_id_collection()} |
662 no_request | timeout
663 Receive a response corresponding to a request identifier saved
665 in ReqIdCollection. All request identifiers of ReqIdCollection
666 must correspond to requests that have been made using send_re‐
667 quest/2 or send_request/4, and all request must have been made
668 by the process calling this function.
669 The Label in the response equals the Label associated with the
671 request identifier that the response corresponds to. The Label
672 of a request identifier is associated when adding the request id
673 in a request identifier collection, or when sending the request
674 using send_request/4.
675 Compared to receive_response/2, the returned result associated
677 with a specific request identifier will be wrapped in a 3-tuple.
678 The first element of this tuple equals the value that would have
679 been produced by receive_response/2, the second element equals
680 the Label associated with the specific request identifier, and
681 the third element NewReqIdCollection is a possibly modified re‐
682 quest identifier collection.
683 If ReqIdCollection is empty, the atom no_request will be re‐
685 turned.
686 Timeout specifies how long to wait for a response. If no re‐
688 sponse is received within the specified time, the function re‐
689 turns timeout. Assuming that the server executes on a node sup‐
690 porting aliases (introduced in OTP 24) all requests identified
691 by ReqIdCollection will also be abandoned. That is, no responses
692 will be received after a timeout. Otherwise, stray responses
693 might be received at a later time.
694 The difference between receive_response/3 and wait_response/3 is
696 that receive_response/3 abandons the requests at timeout so that
697 potential future responses are ignored, while wait_response/3
698 does not.
699 If Delete equals true, the association with Label will have been
701 deleted from ReqIdCollection in the resulting NewReqIdCollec‐
702 tion. If Delete equals false, NewReqIdCollection will equal Re‐
703 qIdCollection. Note that deleting an association is not for free
704 and that a collection containing already handled requests can
705 still be used by subsequent calls to receive_response/3,
706 check_response/3, and wait_response/3. However, without deleting
707 handled associations, the above calls will not be able to detect
708 when there are no more outstanding requests to handle, so you
709 will have to keep track of this some other way than relying on a
710 no_request return. Note that if you pass a collection only con‐
711 taining associations of already handled or abandoned requests to
712 receive_response/3, it will always block until a timeout deter‐
713 mined by Timeout is triggered.
714 reply(Client :: from(), Reply :: term()) -> ok
716 This function can be used by a gen_server process to explicitly
718 send a reply to a client that called call/2,3 or
719 multi_call/2,3,4, when the reply cannot be passed in the return
720 value of Module:handle_call/3.
721 Client must be the From argument provided to the handle_call
723 callback function. Reply is any term passed back to the client
724 as the return value of call/2,3 or multi_call/2,3,4.
725 reqids_add(ReqId :: request_id(),
727 Label :: term(),
728 ReqIdCollection :: request_id_collection()) ->
729 NewReqIdCollection :: request_id_collection()
730 Saves ReqId and associates a Label with the request identifier
732 by adding this information to ReqIdCollection and returning the
733 resulting request identifier collection.
734 reqids_new() -> NewReqIdCollection :: request_id_collection()
736 Returns a new empty request identifier collection. A request
738 identifier collection can be utilized in order the handle multi‐
739 ple outstanding requests.
740 Request identifiers of requests made by send_request/2 can be
742 saved in a request identifier collection using reqids_add/3.
743 Such a collection of request identifiers can later be used in
744 order to get one response corresponding to a request in the col‐
745 lection by passing the collection as argument to receive_re‐
746 sponse/3, wait_response/3, or, check_response/3.
747 reqids_size/1 can be used to determine the amount of request
749 identifiers in a request identifier collection.
750 reqids_size(ReqIdCollection :: request_id_collection()) ->
752 integer() >= 0
753 Returns the amount of request identifiers saved in ReqIdCollec‐
755 tion.
756 reqids_to_list(ReqIdCollection :: request_id_collection()) ->
758 [{ReqId :: request_id(), Label :: term()}]
759 Returns a list of {ReqId, Label} tuples which corresponds to all
761 request identifiers with their associated labels present in the
762 ReqIdCollection collection.
763 send_request(ServerRef :: server_ref(), Request :: term()) ->
765 ReqId :: request_id()
766 Sends an asynchronous call request Request to the gen_server
768 process identified by ServerRef and returns a request identifier
769 ReqId. The return value ReqId shall later be used with re‐
770 ceive_response/2, wait_response/2, or check_response/2 to fetch
771 the actual result of the request. Besides passing the request
772 identifier directly to these functions, it can also be saved in
773 a request identifier collection using reqids_add/3. Such a col‐
774 lection of request identifiers can later be used in order to get
775 one response corresponding to a request in the collection by
776 passing the collection as argument to receive_response/3,
777 wait_response/3, or check_response/3. If you are about to save
778 the request identifier in a request identifier collection, you
779 may want to consider using send_request/4 instead.
780 The call gen_server:receive_response(gen_server:send_re‐
782 quest(ServerRef, Request), Timeout) can be seen as equivalent to
783 gen_server:call(ServerRef, Request, Timeout), ignoring the error
784 handling.
785 The gen_server process calls Module:handle_call/3 to handle the
787 request.
788 See the type server_ref() for the possible values for ServerRef.
790 Request is any term that is passed as the first argument to Mod‐
792 ule:handle_call/3.
793 send_request(ServerRef :: server_ref(),
795 Request :: term(),
796 Label :: term(),
797 ReqIdCollection :: request_id_collection()) ->
798 NewReqIdCollection :: request_id_collection()
799 Sends an asynchronous call request Request to the gen_server
801 process identified by ServerRef. The Label will be associated
802 with the request identifier of the operation and added to the
803 returned request identifier collection NewReqIdCollection. The
804 collection can later be used in order to get one response corre‐
805 sponding to a request in the collection by passing the collec‐
806 tion as argument to receive_response/3, wait_response/3, or,
807 check_response/3.
808 The same as calling gen_server:reqids_add(gen_server:send_re‐
810 quest(ServerRef, Request), Label, ReqIdCollection), but calling
811 send_request/4 is slightly more efficient.
812 start(Module :: module(),
814 Args :: term(),
815 Options :: [start_opt()]) ->
816 start_ret()
817 start(ServerName :: server_name(),
819 Module :: module(),
820 Args :: term(),
821 Options :: [start_opt()]) ->
822 start_ret()
823 Creates a standalone gen_server process, that is, a gen_server
825 process that is not part of a supervision tree and thus has no
826 supervisor.
827 Other than that see start_link/3,4.
829 start_link(Module :: module(),
831 Args :: term(),
832 Options :: [start_opt()]) ->
833 start_ret()
834 start_link(ServerName :: server_name(),
836 Module :: module(),
837 Args :: term(),
838 Options :: [start_opt()]) ->
839 start_ret()
840 Creates a gen_server process as part of a supervision tree. This
842 function is to be called, directly or indirectly, by the super‐
843 visor. For example, it ensures that the gen_server process is
844 linked to the supervisor.
845 The gen_server process calls Module:init/1 to initialize. To en‐
847 sure a synchronized startup procedure, start_link/3,4 does not
848 return until Module:init/1 has returned.
849 Using the argument ServerName creates a gen_server with a regis‐
851 tered name. See type server_name() for different name registra‐
852 tions. If no ServerName is provided, the gen_server process is
853 not registered.
854 Module is the name of the callback module.
856 Args is any term that is passed as the argument to Mod‐
858 ule:init/1.
859 See type start_opt() for Options when starting the gen_server
861 process.
862 See type start_ret() for a description this function's return
864 values.
865 start_monitor(Module :: module(),
867 Args :: term(),
868 Options :: [start_opt()]) ->
869 start_mon_ret()
870 start_monitor(ServerName :: server_name(),
872 Module :: module(),
873 Args :: term(),
874 Options :: [start_opt()]) ->
875 start_mon_ret()
876 Creates a standalone gen_server process, that is, a gen_server
878 process that is not part of a supervision tree (and thus has no
879 supervisor) and atomically sets up a monitor to the newly cre‐
880 ated server.
881 Other than that see start_link/3,4. Note that the return value
883 for a successful start differs in that it returns a monitor ref‐
884 erence. See type start_mon_ret().
885 If the start is not successful, the caller will be blocked until
887 the monitor's 'DOWN' message has been received and removed from
888 the message queue.
889 stop(ServerRef :: server_ref()) -> ok
891 stop(ServerRef :: server_ref(),
893 Reason :: term(),
894 Timeout :: timeout()) ->
895 ok
896 Orders the generic server specified by ServerRef to exit with
898 the specified Reason, default 'normal', and waits for it to ter‐
899 minate. The gen_server process calls Module:terminate/2 before
900 exiting.
901 The function returns ok if the server terminates with the ex‐
903 pected reason. Any other reason than normal, shutdown, or {shut‐
904 down,Term} causes an error report to be issued using logger(3).
905 An exit signal with the same reason is sent to linked processes
906 and ports.
907 Timeout is an integer that specifies how many milliseconds to
909 wait for the server to terminate, or the atom infinity to wait
910 indefinitely, which is the default. If the server has not termi‐
911 nated within the specified time, the call exits the calling
912 process with reason timeout.
913 If the process does not exist, the call exits the calling
915 process with reason noproc, and with reason {nodedown,Node} if
916 the connection fails to the remote Node where the server runs.
917 wait_response(ReqId, WaitTime) -> Result
919 Types:
921 ReqId = request_id()
923 WaitTime = response_timeout()
924 Response =
925 {reply, Reply :: term()} |
926 {error, {Reason :: term(), server_ref()}}
927 Result = Response | timeout
928 Wait for a response corresponding to the request identifier Re‐
930 qId. The request must have been made by send_request/2, and it
931 must have been made by the same process calling this function.
932 WaitTime specifies how long to wait for a reply. If no reply is
934 received within the specified time, the function returns timeout
935 and no cleanup is done, and thus the function can be invoked re‐
936 peatedly until a reply is returned.
937 The return value Reply is passed from the return value of Mod‐
939 ule:handle_call/3.
940 The function returns an error if the gen_server died before a
942 reply was sent.
943 The difference between receive_response/2 and wait_response/2 is
945 that receive_response/2 abandons the request at time-out so that
946 a potential future response is ignored, while wait_response/2
947 does not.
948 wait_response(ReqIdCollection, WaitTime, Delete) -> Result
950 Types:
952 ReqIdCollection = request_id_collection()
954 WaitTime = response_timeout()
955 Delete = boolean()
956 Response =
957 {reply, Reply :: term()} |
958 {error, {Reason :: term(), server_ref()}}
959 Result =
960 {Response,
961 Label :: term(),
962 NewReqIdCollection :: request_id_collection()} |
963 no_request | timeout
964 Wait for a response corresponding to a request identifier saved
966 in ReqIdCollection. All request identifiers of ReqIdCollection
967 must correspond to requests that have been made using send_re‐
968 quest/2 or send_request/4, and all request must have been made
969 by the process calling this function.
970 The Label in the response equals the Label associated with the
972 request identifier that the response corresponds to. The Label
973 of a request identifier is associated when saving the request id
974 in a request identifier collection, or when sending the request
975 using send_request/4.
976 Compared to wait_response/2, the returned result associated with
978 a specific request identifier or an exception associated with a
979 specific request identifier will be wrapped in a 3-tuple. The
980 first element of this tuple equals the value that would have
981 been produced by wait_response/2, the second element equals the
982 Label associated with the specific request identifier, and the
983 third element NewReqIdCollection is a possibly modified request
984 identifier collection.
985 If ReqIdCollection is empty, no_request will be returned. If no
987 response is received before the WaitTime timeout has triggered,
988 the atom timeout is returned. It is valid to continue waiting
989 for a response as many times as needed up until a response has
990 been received and completed by check_response(), receive_re‐
991 sponse(), or wait_response().
992 The difference between receive_response/3 and wait_response/3 is
994 that receive_response/3 abandons requests at timeout so that a
995 potential future responses are ignored, while wait_response/3
996 does not.
997 If Delete equals true, the association with Label will have been
999 deleted from ReqIdCollection in the resulting NewReqIdCollec‐
1000 tion. If Delete equals false, NewReqIdCollection will equal Re‐
1001 qIdCollection. Note that deleting an association is not for free
1002 and that a collection containing already handled requests can
1003 still be used by subsequent calls to wait_response/3, check_re‐
1004 sponse/3, and receive_response/3. However, without deleting han‐
1005 dled associations, the above calls will not be able to detect
1006 when there are no more outstanding requests to handle, so you
1007 will have to keep track of this some other way than relying on a
1008 no_request return. Note that if you pass a collection only con‐
1009 taining associations of already handled or abandoned requests to
1010 wait_response/3, it will always block until a timeout determined
1011 by WaitTime is triggered and then return no_reply.
1012
1014 The following functions are to be exported from a gen_server callback
1015 module.
1016
1018 Module:code_change(OldVsn, State, Extra) -> {ok, NewState} | {error,
1019 Reason}
1020 Types:
1022 OldVsn = Vsn | {down, Vsn}
1024 Vsn = term()
1025 State = NewState = term()
1026 Extra = term()
1027 Reason = term()
1028 Note:
1030 This callback is optional, so callback modules need not export
1031 it. If a release upgrade/downgrade with Change={advanced,Extra}
1032 specified in the appup file is made when code_change/3 isn't im‐
1033 plemented the process will crash with an undef exit reason.
1034 This function is called by a gen_server process when it is to
1037 update its internal state during a release upgrade/downgrade,
1038 that is, when the instruction {update,Module,Change,...}, where
1039 Change={advanced,Extra}, is specifed in the appup file. For more
1040 information, see section Release Handling Instructions in OTP
1041 Design Principles.
1042 For an upgrade, OldVsn is Vsn, and for a downgrade, OldVsn is
1044 {down,Vsn}. Vsn is defined by the vsn attribute(s) of the old
1045 version of the callback module Module. If no such attribute is
1046 defined, the version is the checksum of the Beam file.
1047 State is the internal state of the gen_server process.
1049 Extra is passed "as is" from the {advanced,Extra} part of the
1051 update instruction.
1052 If successful, the function must return the updated internal
1054 state.
1055 If the function returns {error,Reason}, the ongoing upgrade
1057 fails and rolls back to the old release.
1058 Module:format_status(Status) -> NewStatus
1060 Types:
1062 Status = format_status()
1064 NewStatus = format_status()
1065 Note:
1067 This callback is optional, so callback modules need not export
1068 it. The gen_server module provides a default implementation of
1069 this function that returns the callback module state.
1070 If this callback is exported but fails, to hide possibly sensi‐
1072 tive data, the default function will instead return the fact
1073 that format_status/1 has crashed.
1074 This function is called by a gen_server process in the following
1077 situations:
1078 * sys:get_status/1,2 is invoked to get the gen_server status.
1080 * The gen_server process terminates abnormally and logs an er‐
1082 ror.
1083 This callback is used to limit the status of the process re‐
1085 turned by sys:get_status/1,2 or sent to logger.
1086 The callback gets a map Status describing the current status and
1088 shall return a map NewStatus with the same keys, but it may
1089 transform some values.
1090 Two possible use cases for this callback is to remove sensitive
1092 information from the state to prevent it from being printed in
1093 log files, or to compact large irrelevant status items that
1094 would only clutter the logs.
1095 Example:
1097 format_status(Status) ->
1099 maps:map(
1100 fun(state,State) ->
1101 maps:remove(private_key, State);
1102 (message,{password, _Pass}) ->
1103 {password, removed};
1104 (_,Value) ->
1105 Value
1106 end, Status).
1107 Module:format_status(Opt, [PDict, State]) -> Status
1110 Types:
1112 Opt = normal | terminate
1114 PDict = [{Key, Value}]
1115 State = term()
1116 Status = term()
1117 Warning:
1119 This callback is deprecated, in new code use format_status/1.
1120 If a format_status/1 callback exists, then this function will
1121 never be called.
1122 Note:
1125 This callback is optional, so callback modules need not export
1126 it. The gen_server module provides a default implementation of
1127 this function that returns the callback module state.
1128 This function is called by a gen_server process in the following
1131 situations:
1132 * One of sys:get_status/1,2 is invoked to get the gen_server
1134 status. Opt is set to the atom normal.
1135 * The gen_server process terminates abnormally and logs an er‐
1137 ror. Opt is set to the atom terminate.
1138 This function is useful for changing the form and appearance of
1140 the gen_server status for these cases. A callback module wishing
1141 to change the sys:get_status/1,2 return value, as well as how
1142 its status appears in termination error logs, exports an in‐
1143 stance of format_status/2 that returns a term describing the
1144 current status of the gen_server process.
1145 PDict is the current value of the process dictionary of the
1147 gen_server process..
1148 State is the internal state of the gen_server process.
1150 The function is to return Status, a term that changes the de‐
1152 tails of the current state and status of the gen_server process.
1153 There are no restrictions on the form Status can take, but for
1154 the sys:get_status/1,2 case (when Opt is normal), the recom‐
1155 mended form for the Status value is [{data, [{"State", Term}]}],
1156 where Term provides relevant details of the gen_server state.
1157 Following this recommendation is not required, but it makes the
1158 callback module status consistent with the rest of the
1159 sys:get_status/1,2 return value.
1160 One use for this function is to return compact alternative state
1162 representations to avoid that large state terms are printed in
1163 log files.
1164 Module:handle_call(Request, From, State) -> Result
1166 Types:
1168 Request = term()
1170 From = from()
1171 State = term()
1172 Result = {reply,Reply,NewState}
1173 | {reply,Reply,NewState,Timeout}
1174 | {reply,Reply,NewState,hibernate}
1175 | {reply,Reply,NewState,{continue,Continue}}
1176 | {noreply,NewState}
1177 | {noreply,NewState,Timeout}
1178 | {noreply,NewState,hibernate}
1179 | {noreply,NewState,{continue,Continue}}
1180 | {stop,Reason,Reply,NewState}
1181 | {stop,Reason,NewState}
1182 Reply = term()
1183 NewState = term()
1184 Timeout = timeout()
1185 Continue = term()
1186 Reason = term()
1187 Whenever a gen_server process receives a request sent using
1189 call/2,3 or multi_call/2,3,4, this function is called to handle
1190 the request.
1191 State is the internal state of the gen_server process, and New‐
1193 State a possibly updated one.
1194 Request is passed from the same argument provided to call or
1196 multi_call.
1197 The return value Result is interpreted as follows:
1199 {reply,Reply,NewState}
1201 {reply,Reply,NewState,_}: The Reply value is sent back to
1202 the client request and there becomes its return value.
1203 The gen_server process continues executing with the possibly
1205 updated internal state NewState.
1206 {noreply,NewState}
1208 {noreply,NewState,_}: The gen_server process continues exe‐
1209 cuting with the possibly updated internal state NewState.
1210 A reply to the client request has to be created by calling
1212 reply(From, Reply), either in this or in a later callback.
1213 {reply,_,_,Timeout}
1215 {noreply,_,Timeout}: If an integer Timeout is provided, a
1216 time-out occurs unless a request or a message is received
1217 within that many milliseconds. A time-out is represented by
1218 the atom timeout to be handled by the Module:handle_info/2
1219 callback function. Timeout =:= infinity can be used to wait
1220 indefinitely, which is the same as returning a value without
1221 a Timeout member.
1222 {reply,_,_,hibernate}
1224 {noreply,_,hibernate}: The process goes into hibernation
1225 waiting for the next message to arrive (by calling
1226 proc_lib:hibernate/3).
1227 {reply,_,_,{continue,Continue}}
1229 {noreply,_,{continue,Continue}}: The process will execute
1230 the Module:handle_continue/2 callback function, with Con‐
1231 tinue as the first argument.
1232 {stop,Reason,NewState}
1234 {stop,Reason,Reply,NewState}: The gen_server process will
1235 call Module:terminate(Reason,NewState) and then terminate.
1236 {stop,_,Reply,_} will create a reply to the client request
1238 just as {reply,Reply,...} while {stop,_,_} will not, so just
1239 as for {noreply,NewState,...} a reply has to be created by
1240 calling reply(From, Reply) before returning {stop,_,_}.
1241 Module:handle_cast(Request, State) -> Result
1243 Types:
1245 Request = term()
1247 State = term()
1248 Result = {noreply,NewState}
1249 | {noreply,NewState,Timeout}
1250 | {noreply,NewState,hibernate}
1251 | {noreply,NewState,{continue,Continue}}
1252 | {stop,Reason,NewState}
1253 NewState = term()
1254 Timeout = timeout()
1255 Continue = term()
1256 Reason = term()
1257 Whenever a gen_server process receives a request sent using
1259 cast/2 or abcast/2,3, this function is called to handle the re‐
1260 quest.
1261 For a description of the arguments and possible return values,
1263 see Module:handle_call/3.
1264 Module:handle_continue(Continue, State) -> Result
1266 Types:
1268 Continue = term()
1270 State = term()
1271 Result = {noreply,NewState}
1272 | {noreply,NewState,Timeout}
1273 | {noreply,NewState,hibernate}
1274 | {noreply,NewState,{continue,Continue}}
1275 | {stop,Reason,NewState}
1276 NewState = term()
1277 Timeout = timeout()
1278 Continue = term()
1279 Reason = normal | term()
1280 Note:
1282 This callback is optional, so callback modules need to export it
1283 only if they return one of the tuples containing {continue,Con‐
1284 tinue} from another callback. If such a {continue,_} tuple is
1285 used and the callback is not implemented, the process will exit
1286 with undef error.
1287 This function is called by a gen_server process whenever a pre‐
1290 vious callback returns one of the tuples containing {continue,
1291 Continue}. handle_continue/2 is invoked immediately after the
1292 previous callback, which makes it useful for performing work af‐
1293 ter initialization or for splitting the work in a callback in
1294 multiple steps, updating the process state along the way.
1295 For a description of the other arguments and possible return
1297 values, see Module:handle_call/3.
1298 Module:handle_info(Info, State) -> Result
1300 Types:
1302 Info = timeout | term()
1304 State = term()
1305 Result = {noreply,NewState}
1306 | {noreply,NewState,Timeout}
1307 | {noreply,NewState,hibernate}
1308 | {noreply,NewState,{continue,Continue}}
1309 | {stop,Reason,NewState}
1310 NewState = term()
1311 Timeout = timeout()
1312 Reason = normal | term()
1313 Note:
1315 This callback is optional, so callback modules need not export
1316 it. The gen_server module provides a default implementation of
1317 this function that logs about the unexpected Info message, drops
1318 it and returns {noreply, State}.
1319 This function is called by a gen_server process when a time-out
1322 occurs or when it receives any other message than a synchronous
1323 or asynchronous request (or a system message).
1324 Info is either the atom timeout, if a time-out has occurred, or
1326 the received message.
1327 For a description of the other arguments and possible return
1329 values, see Module:handle_call/3.
1330 Module:init(Args) -> Result
1332 Types:
1334 Args = term()
1336 Result = {ok,State}
1337 | {ok,State,Timeout}
1338 | {ok,State,hibernate}
1339 | {ok,State,{continue,Continue}}
1340 | {stop,Reason}
1341 | ignore
1342 State = term()
1343 Timeout = timeout()
1344 Reason = term()
1345 Whenever a gen_server process is started using start/3,4,
1347 start_monitor/3,4, or start_link/3,4, this function is called by
1348 the new process to initialize.
1349 Args is the Args argument provided to the start function.
1351 The return value Result is interpreted as follows:
1353 {ok,State}
1355 {ok,State,_}: Initialization was succesful and State is the
1356 internal state of the gen_server process.
1357 {ok,_,Timeout}
1359 {ok,_,hibernate}
1360 {ok,_,{continue,Continue}}: See the corresponding return
1361 values from Module:handle_call/3 for a description of this
1362 tuple member.
1363 {stop,Reason}
1365 ignore: Initialization failed. An exit signal with this Rea‐
1366 son (or with reason normal if ignore is returned) is sent to
1367 linked processes and ports, notably to the process starting
1368 the gen_server when start_link/3,4 is used.
1369 Module:terminate(Reason, State)
1371 Types:
1373 Reason = normal | shutdown | {shutdown,term()} | term()
1375 State = term()
1376 Note:
1378 This callback is optional, so callback modules need not export
1379 it. The gen_server module provides a default implementation
1380 without cleanup.
1381 This function is called by a gen_server process when it is about
1384 to terminate. It is to be the opposite of Module:init/1 and do
1385 any necessary cleaning up. When it returns, the gen_server
1386 process terminates with Reason. The return value is ignored.
1387 Reason is a term denoting the stop reason and State is the in‐
1389 ternal state of the gen_server process.
1390 Reason depends on why the gen_server process is terminating. If
1392 it is because another callback function has returned a stop tu‐
1393 ple {stop,..}, Reason has the value specified in that tuple. If
1394 it is because of a failure, Reason is the error reason.
1395 If the gen_server process is part of a supervision tree and is
1397 ordered by its supervisor to terminate, this function is called
1398 with Reason=shutdown if the following conditions apply:
1399 * The gen_server process has been set to trap exit signals.
1401 * The shutdown strategy as defined in the child specification
1403 of the supervisor is an integer time-out value, not bru‐
1404 tal_kill.
1405 Even if the gen_server process is not part of a supervision
1407 tree, this function is called if it receives an 'EXIT' message
1408 from its parent. Reason is the same as in the 'EXIT' message.
1409 Otherwise, the gen_server process terminates immediately.
1411 Notice that for any other reason than normal, shutdown, or
1413 {shutdown,Term}, see stop/3, the gen_server process is assumed
1414 to terminate because of an error, and an error report is issued
1415 using logger(3).
1416 When the gen_server process exits, an exit signal with the same
1418 reason is sent to linked processes and ports.
1419
1421 gen_event(3), gen_statem(3), proc_lib(3), supervisor(3), sys(3)
1422Ericsson AB stdlib 4.2 gen_server(3)