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 Note:
78 For some important information about distributed signals, see the
79 Blocking Signaling Over Distribution section in the Processes chapter
80 of the Erlang Reference Manual . Blocking signaling can, for example,
81 cause call timeouts in gen_server to be significantly delayed.
82
85 server_name() =
86 {local, LocalName :: atom()} |
87 {global, GlobalName :: term()} |
88 {via, RegMod :: module(), ViaName :: term()}
89 Name specification to use when starting a gen_server. See func‐
91 tions start/3,4, start_link/3,4, start_monitor/3,4, en‐
92 ter_loop/3,4,5, and the type server_ref() below.
93 {local,LocalName}:
95 Register the gen_server locally as LocalName using regis‐
96 ter/2.
97 {global,GlobalName}:
99 Register the gen_server process id globally as GlobalName
100 using global:register_name/2.
101 {via,RegMod,ViaName}:
103 Register the gen_server process with the registry repre‐
104 sented by RegMod. The RegMod callback is to export the func‐
105 tions register_name/2, unregister_name/1, whereis_name/1,
106 and send/2, which are to behave like the corresponding func‐
107 tions in global. Thus, {via,global,GlobalName} is a valid
108 reference equivalent to {global,GlobalName}.
109 server_ref() =
111 pid() |
112 (LocalName :: atom()) |
113 {Name :: atom(), Node :: atom()} |
114 {global, GlobalName :: term()} |
115 {via, RegMod :: module(), ViaName :: term()}
116 Server specification to use when addressing a gen_server. See
118 call/2,3, cast/2, send_request/2, check_response/2, wait_re‐
119 sponse/2, stop/2,3 and the type server_name() above.
120 It can be:
122 pid():
124 The gen_server's process identifier.
125 LocalName:
127 The gen_server is locally registered as LocalName with reg‐
128 ister/2.
129 {Name,Node}:
131 The gen_server is locally registered on another node.
132 {global,GlobalName}:
134 The gen_server is globally registered in global.
135 {via,RegMod,ViaName}:
137 The gen_server is registered in an alternative process reg‐
138 istry. The registry callback module RegMod is to export
139 functions register_name/2, unregister_name/1,
140 whereis_name/1, and send/2, which are to behave like the
141 corresponding functions in global. Thus, {via,global,Global‐
142 Name} is the same as {global,GlobalName}.
143 start_opt() =
145 {timeout, Timeout :: timeout()} |
146 {spawn_opt, SpawnOptions :: [proc_lib:spawn_option()]} |
147 enter_loop_opt()
148 Options that can be used when starting a gen_server server
150 through, for example, start_link/3,4.
151 {timeout,Timeout}:
153 How many milliseconds the gen_server process is allowed to
154 spend initializing or it is terminated and the start func‐
155 tion returns {error,timeout}.
156 {spawn_opt,SpawnOptions}:
158 The SpawnOptions option list is passed to the function used
159 to spawn the gen_server; see spawn_opt/2.
160 Note:
162 Using spawn option monitor is not allowed, it causes a badarg
163 failure.
164 enter_loop_opt():
167 See the type enter_loop_opt() below for more start options
168 that are also allowed by enter_loop/3,4,5.
169 enter_loop_opt() =
171 {hibernate_after, HibernateAfterTimeout :: timeout()} |
172 {debug, Dbgs :: [sys:debug_option()]}
173 Options that can be used when starting a gen_server server
175 through enter_loop/3-5 or the start functions such as
176 start_link/3,4.
177 {hibernate_after,HibernateAfterTimeout}:
179 Specifies that the gen_server process awaits any message for
180 HibernateAfterTimeout milliseconds and if no message is re‐
181 ceived, the process goes into hibernation automatically (by
182 calling proc_lib:hibernate/3).
183 {debug,Dbgs}:
185 For every entry in Dbgs, the corresponding function in
186 sys(3) is called.
187 start_ret() =
189 {ok, Pid :: pid()} | ignore | {error, Reason :: term()}
190 Return value from the start/3,4 and start_link/3,4 functions.
192 {ok,Pid}:
194 The gen_server process was succesfully created and initial‐
195 ized, with the process identifier Pid.
196 {error,{already_started,OtherPid}}:
198 A process with the specified ServerName exists already with
199 the process identifier OtherPid. This gen_server was not
200 started, or rather exited with reason normal before calling
201 Module:init/1.
202 {error,timeout}:
204 The gen_server process failed to initialize since Mod‐
205 ule:init/1 did not return within the start timeout. The
206 gen_server process was killed with exit(_, kill).
207 ignore:
209 The gen_server process failed to initialize since Mod‐
210 ule:init/1 returned ignore.
211 {error,Reason}:
213 The gen_server process failed to initialize since Mod‐
214 ule:init/1 returned {stop,Reason}, {error,Reason}, or it
215 failed with reason Reason.
216 See Module:init/1 about the exit reason for the gen_server
218 process when it fails to initialize.
219 start_mon_ret() =
221 {ok, {Pid :: pid(), MonRef :: reference()}} |
222 ignore |
223 {error, Reason :: term()}
224 Return value from the start_monitor/3,4 functions. The same as
226 type start_ret() except that for a succesful start it returns
227 both the process identifier Pid and a monitor/2,3 reference()
228 MonRef.
229 from() = {Client :: pid(), Tag :: reply_tag()}
231 Destination, given to the gen_server as the first argument to
233 the callback function Module:handle_call/3, to be used by the
234 when replying through reply/2 (instead of through the callback
235 function's return value) to the process Client that has called
236 the gen_server using call/2,3. Tag is a term that is unique for
237 this call/request instance.
238 reply_tag()
240 A handle that associates a reply to the corresponding request.
242 request_id()
244 An opaque request identifier. See send_request/2 for details.
246 request_id_collection()
248 An opaque collection of request identifiers (request_id()) where
250 each request identifier can be associated with a label chosen by
251 the user. For more information see reqids_new/0.
252 response_timeout() = timeout() | {abs, integer()}
254 Used to set a time limit on how long to wait for a response us‐
256 ing either receive_response/2, receive_response/3, wait_re‐
257 sponse/2, or wait_response/3. The time unit used is millisecond.
258 Currently valid values:
259 0..4294967295:
261 Timeout relative to current time in milliseconds.
262 infinity:
264 Infinite timeout. That is, the operation will never time
265 out.
266 {abs, Timeout}:
268 An absolute Erlang monotonic time timeout in milliseconds.
269 That is, the operation will time out when erlang:mono‐
270 tonic_time(millisecond) returns a value larger than or equal
271 to Timeout. Timeout is not allowed to identify a time fur‐
272 ther into the future than 4294967295 milliseconds. Identify‐
273 ing the timeout using an absolute timeout value is espe‐
274 cially handy when you have a deadline for responses corre‐
275 sponding to a complete collection of requests (re‐
276 quest_id_collection()) , since you do not have to recalcu‐
277 late the relative time until the deadline over and over
278 again.
279 format_status() =
281 #{state => term(),
282 message => term(),
283 reason => term(),
284 log => [sys:system_event()]}
285 A map that describes the gen_server status. The keys are:
287 state:
289 The internal state of the gen_server process.
290 message:
292 The message that caused the server to terminate.
293 reason:
295 The reason that caused the server to terminate.
296 log:
298 The sys log of the server.
299 New associations may be added to the status map without prior
301 notice.
302
304 abcast(Name :: atom(), Request :: term()) -> abcast
305 abcast(Nodes :: [node()], Name :: atom(), Request :: term()) ->
307 abcast
308 Sends an asynchronous request to the gen_server processes lo‐
310 cally registered as Name at the specified nodes. The function
311 returns immediately and ignores nodes that do not exist, or
312 where the gen_server Name does not exist. The gen_server pro‐
313 cesses call Module:handle_cast/2 to handle the request.
314 For a description of the arguments, see multi_call/2,3,4.
316 call(ServerRef :: server_ref(), Request :: term()) ->
318 Reply :: term()
319 call(ServerRef :: server_ref(),
321 Request :: term(),
322 Timeout :: timeout()) ->
323 Reply :: term()
324 Makes a synchronous call to the ServerRef of the gen_server
326 process by sending a request and waiting until a reply arrives
327 or a time-out occurs. The gen_server process calls Module:han‐
328 dle_call/3 to handle the request.
329 See also ServerRef's type server_ref().
331 Request is any term that is passed as the first argument to Mod‐
333 ule:handle_call/3.
334 Timeout is an integer that specifies how many milliseconds to
336 wait for a reply, or the atom infinity to wait indefinitely. De‐
337 faults to 5000. If no reply is received within the specified
338 time, this function exits the calling process with an exit term
339 containing Reason = timeout as described below.
340 Note:
342 Before OTP 24, if the caller uses (try...)catch to avoid process
343 exit, and the server happens to just be late with the reply, it
344 may arrive to the process message queue any time later. The
345 calling process must therefore after catching a time-out exit be
346 prepared to receive garbage message(s) on the form {reference(),
347 _} and deal with them appropriately (discard them) so they do
348 not clog the process message queue or gets mistaken for other
349 messages.
350 Starting with OTP 24, gen_server:call uses process aliases, so
352 late replies will not be received.
353 The return value Reply is passed from the return value of Mod‐
356 ule:handle_call/3.
357 This call may exit the calling process with an exit term on the
359 form {Reason, Location} where Location = {gen_server,call,Ar‐
360 gList} and Reason can be (at least) one of:
361 timeout:
363 The call was aborted after waiting Timeout milliseconds for
364 a reply, as described above.
365 noproc:
367 The ServerRef refers to a server by name (it is not a pid())
368 and looking up the server process failed, or the pid() was
369 already terminated.
370 {nodedown,Node}:
372 The ServerRef refers to a server on the remote node Node and
373 the connection to that node failed.
374 calling_self:
376 A call to self() would hang indefinitely.
377 shutdown
379 : The server was stopped during the call by its supervisor.
380 See also stop/3.
381 normal
383 {shutdown,Term}
384 : The server stopped during the call by returning {stop,Rea‐
385 son,_} from one of its callbacks without replying to this
386 call. See also stop/3.
387 _OtherTerm:
389 The server process exited during the call, with reason Rea‐
390 son. Either by returning {stop,Reason,_} from one of its
391 callbacks (without replying to this call), by raising an ex‐
392 ception, or due to getting an exit signal it did not trap.
393 cast(ServerRef :: server_ref(), Request :: term()) -> ok
395 Sends an asynchronous request to the ServerRef of the gen_server
397 process and returns ok immediately, ignoring if the destination
398 node or gen_server process does not exist. The gen_server
399 process calls Module:handle_cast/2 to handle the request.
400 See also ServerRef's type server_ref().
402 Request is any term that is passed as the first argument to Mod‐
404 ule:handle_cast/2.
405 check_response(Msg, ReqId) -> Result
407 Types:
409 Msg = term()
411 ReqId = request_id()
412 Response =
413 {reply, Reply :: term()} |
414 {error, {Reason :: term(), server_ref()}}
415 Result = Response | no_reply
416 Check if Msg is a response corresponding to the request identi‐
418 fier ReqId. The request must have been made by send_request/2,
419 and it must have been made by the same process calling this
420 function.
421 If Msg is a response corresponding to ReqId the response is re‐
423 turned; otherwise, no_reply is returned and no cleanup is done,
424 and thus the function must be invoked repeatedly until a re‐
425 sponse is returned.
426 The return value Reply is passed from the return value of Mod‐
428 ule:handle_call/3.
429 The function returns an error if the gen_server died before a
431 reply was sent.
432 check_response(Msg, ReqIdCollection, Delete) -> Result
434 Types:
436 Msg = term()
438 ReqIdCollection = request_id_collection()
439 Delete = boolean()
440 Response =
441 {reply, Reply :: term()} |
442 {error, {Reason :: term(), server_ref()}}
443 Result =
444 {Response,
445 Label :: term(),
446 NewReqIdCollection :: request_id_collection()} |
447 no_request | no_reply
448 Check if Msg is a response corresponding to a request identifier
450 saved in ReqIdCollection. All request identifiers of ReqIdCol‐
451 lection must correspond to requests that have been made using
452 send_request/2 or send_request/4, and all requests must have
453 been made by the process calling this function.
454 The Label in the response equals the Label associated with the
456 request identifier that the response corresponds to. The Label
457 of a request identifier is associated when saving the request id
458 in a request identifier collection, or when sending the request
459 using send_request/4.
460 Compared to check_response/2, the returned result associated
462 with a specific request identifier or an exception associated
463 with a specific request identifier will be wrapped in a 3-tuple.
464 The first element of this tuple equals the value that would have
465 been produced by check_response/2, the second element equals the
466 Label associated with the specific request identifier, and the
467 third element NewReqIdCollection is a possibly modified request
468 identifier collection.
469 If ReqIdCollection is empty, the atom no_request will be re‐
471 turned. If Msg does not correspond to any of the request identi‐
472 fiers in ReqIdCollection, the atom no_reply is returned.
473 If Delete equals true, the association with Label will have been
475 deleted from ReqIdCollection in the resulting NewReqIdCollec‐
476 tion. If Delete equals false, NewReqIdCollection will equal Re‐
477 qIdCollection. Note that deleting an association is not for free
478 and that a collection containing already handled requests can
479 still be used by subsequent calls to check_response/3, re‐
480 ceive_response/3, and wait_response/3. However, without deleting
481 handled associations, the above calls will not be able to detect
482 when there are no more outstanding requests to handle, so you
483 will have to keep track of this some other way than relying on a
484 no_request return. Note that if you pass a collection only con‐
485 taining associations of already handled or abandoned requests to
486 check_response/3, it will always return no_reply.
487 enter_loop(Module :: module(),
489 Options :: [enter_loop_opt()],
490 State :: term()) ->
491 no_return()
492 enter_loop(Module :: module(),
494 Options :: [enter_loop_opt()],
495 State :: term(),
496 ServerName :: server_name() | pid()) ->
497 no_return()
498 enter_loop(Module :: module(),
500 Options :: [enter_loop_opt()],
501 State :: term(),
502 Timeout :: timeout()) ->
503 no_return()
504 enter_loop(Module :: module(),
506 Options :: [enter_loop_opt()],
507 State :: term(),
508 Hibernate :: hibernate) ->
509 no_return()
510 enter_loop(Module :: module(),
512 Options :: [enter_loop_opt()],
513 State :: term(),
514 Cont :: {continue, term()}) ->
515 no_return()
516 enter_loop(Module :: module(),
518 Options :: [enter_loop_opt()],
519 State :: term(),
520 ServerName :: server_name() | pid(),
521 Timeout :: timeout()) ->
522 no_return()
523 enter_loop(Module :: module(),
525 Options :: [enter_loop_opt()],
526 State :: term(),
527 ServerName :: server_name() | pid(),
528 Hibernate :: hibernate) ->
529 no_return()
530 enter_loop(Module :: module(),
532 Options :: [enter_loop_opt()],
533 State :: term(),
534 ServerName :: server_name() | pid(),
535 Cont :: {continue, term()}) ->
536 no_return()
537 Makes an existing process a gen_server process. Does not return,
539 instead the calling process enters the gen_server process re‐
540 ceive loop and becomes a gen_server process. The process must
541 have been started using one of the start functions in
542 proc_lib(3). The user is responsible for any initialization of
543 the process, including registering a name for it.
544 This function is useful when a more complex initialization pro‐
546 cedure is needed than the gen_server process behavior provides.
547 Module, Options, and ServerName have the same meanings as when
549 calling start[_link|_monitor]/3,4 or it can be self() for an
550 anonymous server, which is the same as calling an enter_loop/3,4
551 function without a ServerName argument. However, if ServerName
552 is specified (and not as self()), the process must have been
553 registered accordingly before this function is called.
554 State, Timeout, Hibernate and Cont have the same meanings as in
556 the return value of Module:init/1, which is not called when en‐
557 ter_loop/3,4,5 is used. Note that to adhere to the gen_server
558 Behaviour such a callback function needs to be defined, and it
559 might as well be the one used when starting the gen_server
560 process through proc_lib, and then be the one that calls en‐
561 ter_loop/3,4,5. But if such a Module:init/1 function in for ex‐
562 ample error cases cannot call enter_loop/3,4,5, it should return
563 a value that follows the type specification for Module:init/1
564 such as ignore, although that value will be lost when returning
565 to the spawning function.
566 This function fails if the calling process was not started by a
568 proc_lib start function, or if it is not registered according to
569 ServerName.
570 multi_call(Name :: atom(), Request :: term()) ->
572 {Replies :: [{Node :: node(), Reply :: term()}],
573 BadNodes :: [node()]}
574 multi_call(Nodes :: [node()], Name :: atom(), Request :: term()) ->
576 {Replies :: [{Node :: node(), Reply :: term()}],
577 BadNodes :: [node()]}
578 multi_call(Nodes :: [node()],
580 Name :: atom(),
581 Request :: term(),
582 Timeout :: timeout()) ->
583 {Replies :: [{Node :: node(), Reply :: term()}],
584 BadNodes :: [node()]}
585 Makes a synchronous call to all gen_server processes locally
587 registered as Name at the specified nodes, by first sending the
588 request to the nodes, and then waiting for the replies. The
589 gen_server processes on the nodes call Module:handle_call/3 to
590 handle the request.
591 The function returns a tuple {Replies,BadNodes}, where Replies
593 is a list of {Node,Reply} tuples, and BadNodes is a list of
594 nodes that either did not exist, where Name was not a registered
595 gen_server, or where it did not reply.
596 Nodes is a list of node names to which the request is to be
598 sent. Default value is the list of all known nodes
599 [node()|nodes()].
600 Name is the locally registered name for each gen_server process.
602 Request is any term that is passed as the first argument to Mod‐
604 ule:handle_call/3.
605 Timeout is an integer that specifies how many milliseconds to
607 wait for all replies, or the atom infinity to wait indefinitely,
608 which is the default. If no reply is received from a node within
609 the specified time, the node is added to BadNodes.
610 When a reply Reply is received from the gen_server process at a
612 node Node, {Node,Reply} is added to Replies. Reply is passed
613 from the return value of Module:handle_call/3.
614 Warning:
616 If one of the nodes cannot process monitors, for example, C or
617 Java nodes, and the gen_server process is not started when the
618 requests are sent, but starts within 2 seconds, this function
619 waits the whole Timeout, which may be infinity.
620 This problem does not exist if all nodes are Erlang nodes.
622 To prevent late answers (after the time-out) from polluting the
625 message queue of the caller, a middleman process is used to do
626 the calls. Late answers are then discarded when they arrive to a
627 terminated process.
628 receive_response(ReqId, Timeout) -> Result
630 Types:
632 ReqId = request_id()
634 Timeout = response_timeout()
635 Response =
636 {reply, Reply :: term()} |
637 {error, {Reason :: term(), server_ref()}}
638 Result = Response | timeout
639 Receive a response corresponding to the request identifier Re‐
641 qId. The request must have been made by send_request/2, and it
642 must have been made by the same process calling this function.
643 Timeout specifies how long to wait for a response. If no re‐
645 sponse is received within the specified time, the function re‐
646 turns timeout. Assuming that the server executes on a node sup‐
647 porting aliases (introduced in OTP 24) the request will also be
648 abandoned. That is, no response will be received after a time‐
649 out. Otherwise, a stray response might be received at a later
650 time.
651 The return value Reply is passed from the return value of Mod‐
653 ule:handle_call/3.
654 The function returns an error if the gen_server died before a
656 reply was sent.
657 The difference between receive_response/2 and wait_response/2 is
659 that receive_response/2 abandons the request at timeout so that
660 a potential future response is ignored, while wait_response/2
661 does not.
662 receive_response(ReqIdCollection, Timeout, Delete) -> Result
664 Types:
666 ReqIdCollection = request_id_collection()
668 Timeout = response_timeout()
669 Delete = boolean()
670 Response =
671 {reply, Reply :: term()} |
672 {error, {Reason :: term(), server_ref()}}
673 Result =
674 {Response,
675 Label :: term(),
676 NewReqIdCollection :: request_id_collection()} |
677 no_request | timeout
678 Receive a response corresponding to a request identifier saved
680 in ReqIdCollection. All request identifiers of ReqIdCollection
681 must correspond to requests that have been made using send_re‐
682 quest/2 or send_request/4, and all requests must have been made
683 by the process calling this function.
684 The Label in the response equals the Label associated with the
686 request identifier that the response corresponds to. The Label
687 of a request identifier is associated when adding the request id
688 in a request identifier collection, or when sending the request
689 using send_request/4.
690 Compared to receive_response/2, the returned result associated
692 with a specific request identifier will be wrapped in a 3-tuple.
693 The first element of this tuple equals the value that would have
694 been produced by receive_response/2, the second element equals
695 the Label associated with the specific request identifier, and
696 the third element NewReqIdCollection is a possibly modified re‐
697 quest identifier collection.
698 If ReqIdCollection is empty, the atom no_request will be re‐
700 turned.
701 Timeout specifies how long to wait for a response. If no re‐
703 sponse is received within the specified time, the function re‐
704 turns timeout. Assuming that the server executes on a node sup‐
705 porting aliases (introduced in OTP 24) all requests identified
706 by ReqIdCollection will also be abandoned. That is, no responses
707 will be received after a timeout. Otherwise, stray responses
708 might be received at a later time.
709 The difference between receive_response/3 and wait_response/3 is
711 that receive_response/3 abandons the requests at timeout so that
712 potential future responses are ignored, while wait_response/3
713 does not.
714 If Delete equals true, the association with Label will have been
716 deleted from ReqIdCollection in the resulting NewReqIdCollec‐
717 tion. If Delete equals false, NewReqIdCollection will equal Re‐
718 qIdCollection. Note that deleting an association is not for free
719 and that a collection containing already handled requests can
720 still be used by subsequent calls to receive_response/3,
721 check_response/3, and wait_response/3. However, without deleting
722 handled associations, the above calls will not be able to detect
723 when there are no more outstanding requests to handle, so you
724 will have to keep track of this some other way than relying on a
725 no_request return. Note that if you pass a collection only con‐
726 taining associations of already handled or abandoned requests to
727 receive_response/3, it will always block until a timeout deter‐
728 mined by Timeout is triggered.
729 reply(Client :: from(), Reply :: term()) -> ok
731 This function can be used by a gen_server process to explicitly
733 send a reply to a client that called call/2,3 or
734 multi_call/2,3,4, when the reply cannot be passed in the return
735 value of Module:handle_call/3.
736 Client must be the From argument provided to the handle_call
738 callback function. Reply is any term passed back to the client
739 as the return value of call/2,3 or multi_call/2,3,4.
740 reqids_add(ReqId :: request_id(),
742 Label :: term(),
743 ReqIdCollection :: request_id_collection()) ->
744 NewReqIdCollection :: request_id_collection()
745 Saves ReqId and associates a Label with the request identifier
747 by adding this information to ReqIdCollection and returning the
748 resulting request identifier collection.
749 reqids_new() -> NewReqIdCollection :: request_id_collection()
751 Returns a new empty request identifier collection. A request
753 identifier collection can be utilized in order the handle multi‐
754 ple outstanding requests.
755 Request identifiers of requests made by send_request/2 can be
757 saved in a request identifier collection using reqids_add/3.
758 Such a collection of request identifiers can later be used in
759 order to get one response corresponding to a request in the col‐
760 lection by passing the collection as argument to receive_re‐
761 sponse/3, wait_response/3, or, check_response/3.
762 reqids_size/1 can be used to determine the amount of request
764 identifiers in a request identifier collection.
765 reqids_size(ReqIdCollection :: request_id_collection()) ->
767 integer() >= 0
768 Returns the amount of request identifiers saved in ReqIdCollec‐
770 tion.
771 reqids_to_list(ReqIdCollection :: request_id_collection()) ->
773 [{ReqId :: request_id(), Label :: term()}]
774 Returns a list of {ReqId, Label} tuples which corresponds to all
776 request identifiers with their associated labels present in the
777 ReqIdCollection collection.
778 send_request(ServerRef :: server_ref(), Request :: term()) ->
780 ReqId :: request_id()
781 Sends an asynchronous call request Request to the gen_server
783 process identified by ServerRef and returns a request identifier
784 ReqId. The return value ReqId shall later be used with re‐
785 ceive_response/2, wait_response/2, or check_response/2 to fetch
786 the actual result of the request. Besides passing the request
787 identifier directly to these functions, it can also be saved in
788 a request identifier collection using reqids_add/3. Such a col‐
789 lection of request identifiers can later be used in order to get
790 one response corresponding to a request in the collection by
791 passing the collection as argument to receive_response/3,
792 wait_response/3, or check_response/3. If you are about to save
793 the request identifier in a request identifier collection, you
794 may want to consider using send_request/4 instead.
795 The call gen_server:receive_response(gen_server:send_re‐
797 quest(ServerRef, Request), Timeout) can be seen as equivalent to
798 gen_server:call(ServerRef, Request, Timeout), ignoring the error
799 handling.
800 The gen_server process calls Module:handle_call/3 to handle the
802 request.
803 See the type server_ref() for the possible values for ServerRef.
805 Request is any term that is passed as the first argument to Mod‐
807 ule:handle_call/3.
808 send_request(ServerRef :: server_ref(),
810 Request :: term(),
811 Label :: term(),
812 ReqIdCollection :: request_id_collection()) ->
813 NewReqIdCollection :: request_id_collection()
814 Sends an asynchronous call request Request to the gen_server
816 process identified by ServerRef. The Label will be associated
817 with the request identifier of the operation and added to the
818 returned request identifier collection NewReqIdCollection. The
819 collection can later be used in order to get one response corre‐
820 sponding to a request in the collection by passing the collec‐
821 tion as argument to receive_response/3, wait_response/3, or,
822 check_response/3.
823 The same as calling gen_server:reqids_add(gen_server:send_re‐
825 quest(ServerRef, Request), Label, ReqIdCollection), but calling
826 send_request/4 is slightly more efficient.
827 start(Module :: module(),
829 Args :: term(),
830 Options :: [start_opt()]) ->
831 start_ret()
832 start(ServerName :: server_name(),
834 Module :: module(),
835 Args :: term(),
836 Options :: [start_opt()]) ->
837 start_ret()
838 Creates a standalone gen_server process, that is, a gen_server
840 process that is not part of a supervision tree and thus has no
841 supervisor.
842 Other than that see start_link/3,4.
844 start_link(Module :: module(),
846 Args :: term(),
847 Options :: [start_opt()]) ->
848 start_ret()
849 start_link(ServerName :: server_name(),
851 Module :: module(),
852 Args :: term(),
853 Options :: [start_opt()]) ->
854 start_ret()
855 Creates a gen_server process as part of a supervision tree. This
857 function is to be called, directly or indirectly, by the super‐
858 visor. For example, it ensures that the gen_server process is
859 spawned as linked to the caller (supervisor).
860 The gen_server process calls Module:init/1 to initialize. To en‐
862 sure a synchronized startup procedure, start_link/3,4 does not
863 return until Module:init/1 has returned or failed.
864 Using the argument ServerName creates a gen_server with a regis‐
866 tered name. See type server_name() for different name registra‐
867 tions. If no ServerName is provided, the gen_server process is
868 not registered.
869 Module is the name of the callback module.
871 Args is any term that is passed as the argument to Mod‐
873 ule:init/1.
874 See type start_opt() for Options when starting the gen_server
876 process.
877 See type start_ret() for a description this function's return
879 values.
880 If start_link/3,4 returns ignore or {error,_}, the started
882 gen_server process has terminated. If an 'EXIT' message was de‐
883 livered to the calling process (due to the process link), that
884 message has been consumed.
885 Warning:
887 Before OTP 26.0, if the started gen_server process returned e.g.
888 {stop,Reason} from Module:init/1, this function could return
889 {error,Reason} before the started gen_statem process had termi‐
890 nated so starting again might fail because VM resources such as
891 the registered name was not yet unregistered. An 'EXIT' message
892 could arrive later to the process calling this function.
893 But if the started gen_server process instead failed during Mod‐
895 ule:init/1, a process link {'EXIT',Pid,Reason} message caused
896 this function to return {error,Reason} so the 'EXIT' message had
897 been consumed and the started gen_statem process had terminated.
898 Since it was impossible to tell the difference between these two
900 cases from start_link/3,4's return value, this inconsistency was
901 cleaned up in OTP 26.0.
902 The difference between returning {stop,_} and {error,_} from
905 Module:init/1, is that {error,_} results in a graceful
906 ("silent") termination since the gen_server process exits with
907 reason normal.
908 start_monitor(Module :: module(),
910 Args :: term(),
911 Options :: [start_opt()]) ->
912 start_mon_ret()
913 start_monitor(ServerName :: server_name(),
915 Module :: module(),
916 Args :: term(),
917 Options :: [start_opt()]) ->
918 start_mon_ret()
919 Creates a standalone gen_server process, that is, a gen_server
921 process that is not part of a supervision tree (and thus has no
922 supervisor) and atomically sets up a monitor to the newly cre‐
923 ated server.
924 Other than that see start_link/3,4. Note that the return value
926 for a successful start differs in that it returns a monitor ref‐
927 erence. See type start_mon_ret().
928 If the start is not successful, the caller will be blocked until
930 the monitor's 'DOWN' message has been received and removed from
931 the message queue.
932 stop(ServerRef :: server_ref()) -> ok
934 stop(ServerRef :: server_ref(),
936 Reason :: term(),
937 Timeout :: timeout()) ->
938 ok
939 Orders the generic server specified by ServerRef to exit with
941 the specified Reason, default 'normal', and waits for it to ter‐
942 minate. The gen_server process calls Module:terminate/2 before
943 exiting.
944 The function returns ok if the server terminates with the ex‐
946 pected reason. Any other reason than normal, shutdown, or {shut‐
947 down,Term} causes an error report to be issued using logger(3).
948 An exit signal with the same reason is sent to linked processes
949 and ports.
950 Timeout is an integer that specifies how many milliseconds to
952 wait for the server to terminate, or the atom infinity to wait
953 indefinitely, which is the default. If the server has not termi‐
954 nated within the specified time, the call exits the calling
955 process with reason timeout.
956 If the process does not exist, the call exits the calling
958 process with reason noproc, and with reason {nodedown,Node} if
959 the connection fails to the remote Node where the server runs.
960 wait_response(ReqId, WaitTime) -> Result
962 Types:
964 ReqId = request_id()
966 WaitTime = response_timeout()
967 Response =
968 {reply, Reply :: term()} |
969 {error, {Reason :: term(), server_ref()}}
970 Result = Response | timeout
971 Wait for a response corresponding to the request identifier Re‐
973 qId. The request must have been made by send_request/2, and it
974 must have been made by the same process calling this function.
975 WaitTime specifies how long to wait for a reply. If no reply is
977 received within the specified time, the function returns timeout
978 and no cleanup is done, and thus the function can be invoked re‐
979 peatedly until a reply is returned.
980 The return value Reply is passed from the return value of Mod‐
982 ule:handle_call/3.
983 The function returns an error if the gen_server died before a
985 reply was sent.
986 The difference between receive_response/2 and wait_response/2 is
988 that receive_response/2 abandons the request at time-out so that
989 a potential future response is ignored, while wait_response/2
990 does not.
991 wait_response(ReqIdCollection, WaitTime, Delete) -> Result
993 Types:
995 ReqIdCollection = request_id_collection()
997 WaitTime = response_timeout()
998 Delete = boolean()
999 Response =
1000 {reply, Reply :: term()} |
1001 {error, {Reason :: term(), server_ref()}}
1002 Result =
1003 {Response,
1004 Label :: term(),
1005 NewReqIdCollection :: request_id_collection()} |
1006 no_request | timeout
1007 Wait for a response corresponding to a request identifier saved
1009 in ReqIdCollection. All request identifiers of ReqIdCollection
1010 must correspond to requests that have been made using send_re‐
1011 quest/2 or send_request/4, and all requests must have been made
1012 by the process calling this function.
1013 The Label in the response equals the Label associated with the
1015 request identifier that the response corresponds to. The Label
1016 of a request identifier is associated when saving the request id
1017 in a request identifier collection, or when sending the request
1018 using send_request/4.
1019 Compared to wait_response/2, the returned result associated with
1021 a specific request identifier or an exception associated with a
1022 specific request identifier will be wrapped in a 3-tuple. The
1023 first element of this tuple equals the value that would have
1024 been produced by wait_response/2, the second element equals the
1025 Label associated with the specific request identifier, and the
1026 third element NewReqIdCollection is a possibly modified request
1027 identifier collection.
1028 If ReqIdCollection is empty, no_request will be returned. If no
1030 response is received before the WaitTime timeout has triggered,
1031 the atom timeout is returned. It is valid to continue waiting
1032 for a response as many times as needed up until a response has
1033 been received and completed by check_response(), receive_re‐
1034 sponse(), or wait_response().
1035 The difference between receive_response/3 and wait_response/3 is
1037 that receive_response/3 abandons requests at timeout so that po‐
1038 tential future responses are ignored, while wait_response/3 does
1039 not.
1040 If Delete equals true, the association with Label will have been
1042 deleted from ReqIdCollection in the resulting NewReqIdCollec‐
1043 tion. If Delete equals false, NewReqIdCollection will equal Re‐
1044 qIdCollection. Note that deleting an association is not for free
1045 and that a collection containing already handled requests can
1046 still be used by subsequent calls to wait_response/3, check_re‐
1047 sponse/3, and receive_response/3. However, without deleting han‐
1048 dled associations, the above calls will not be able to detect
1049 when there are no more outstanding requests to handle, so you
1050 will have to keep track of this some other way than relying on a
1051 no_request return. Note that if you pass a collection only con‐
1052 taining associations of already handled or abandoned requests to
1053 wait_response/3, it will always block until a timeout determined
1054 by WaitTime is triggered and then return no_reply.
1055
1057 The following functions are to be exported from a gen_server callback
1058 module.
1059
1061 Module:code_change(OldVsn, State, Extra) -> {ok, NewState} | {error,
1062 Reason}
1063 Types:
1065 OldVsn = Vsn | {down, Vsn}
1067 Vsn = term()
1068 State = NewState = term()
1069 Extra = term()
1070 Reason = term()
1071 Note:
1073 This callback is optional, so callback modules need not export
1074 it. If a release upgrade/downgrade with Change={advanced,Extra}
1075 specified in the appup file is made when code_change/3 isn't im‐
1076 plemented the process will crash with an undef exit reason.
1077 This function is called by a gen_server process when it is to
1080 update its internal state during a release upgrade/downgrade,
1081 that is, when the instruction {update,Module,Change,...}, where
1082 Change={advanced,Extra}, is specifed in the appup file. For more
1083 information, see section Release Handling Instructions in OTP
1084 Design Principles.
1085 For an upgrade, OldVsn is Vsn, and for a downgrade, OldVsn is
1087 {down,Vsn}. Vsn is defined by the vsn attribute(s) of the old
1088 version of the callback module Module. If no such attribute is
1089 defined, the version is the checksum of the Beam file.
1090 State is the internal state of the gen_server process.
1092 Extra is passed "as is" from the {advanced,Extra} part of the
1094 update instruction.
1095 If successful, the function must return the updated internal
1097 state.
1098 If the function returns {error,Reason}, the ongoing upgrade
1100 fails and rolls back to the old release.
1101 Module:format_status(Status) -> NewStatus
1103 Types:
1105 Status = format_status()
1107 NewStatus = format_status()
1108 Note:
1110 This callback is optional, so callback modules need not export
1111 it. The gen_server module provides a default implementation of
1112 this function that returns the callback module state.
1113 If this callback is exported but fails, to hide possibly sensi‐
1115 tive data, the default function will instead return the fact
1116 that format_status/1 has crashed.
1117 This function is called by a gen_server process in the following
1120 situations:
1121 * sys:get_status/1,2 is invoked to get the gen_server status.
1123 * The gen_server process terminates abnormally and logs an er‐
1125 ror.
1126 This callback is used to limit the status of the process re‐
1128 turned by sys:get_status/1,2 or sent to logger.
1129 The callback gets a map Status describing the current status and
1131 shall return a map NewStatus with the same keys, but it may
1132 transform some values.
1133 Two possible use cases for this callback is to remove sensitive
1135 information from the state to prevent it from being printed in
1136 log files, or to compact large irrelevant status items that
1137 would only clutter the logs.
1138 Example:
1140 format_status(Status) ->
1142 maps:map(
1143 fun(state,State) ->
1144 maps:remove(private_key, State);
1145 (message,{password, _Pass}) ->
1146 {password, removed};
1147 (_,Value) ->
1148 Value
1149 end, Status).
1150 Module:format_status(Opt, [PDict, State]) -> Status
1153 Types:
1155 Opt = normal | terminate
1157 PDict = [{Key, Value}]
1158 State = term()
1159 Status = term()
1160 Warning:
1162 This callback is deprecated, in new code use format_status/1.
1163 If a format_status/1 callback exists, then this function will
1164 never be called.
1165 Note:
1168 This callback is optional, so callback modules need not export
1169 it. The gen_server module provides a default implementation of
1170 this function that returns the callback module state.
1171 This function is called by a gen_server process in the following
1174 situations:
1175 * One of sys:get_status/1,2 is invoked to get the gen_server
1177 status. Opt is set to the atom normal.
1178 * The gen_server process terminates abnormally and logs an er‐
1180 ror. Opt is set to the atom terminate.
1181 This function is useful for changing the form and appearance of
1183 the gen_server status for these cases. A callback module wishing
1184 to change the sys:get_status/1,2 return value, as well as how
1185 its status appears in termination error logs, exports an in‐
1186 stance of format_status/2 that returns a term describing the
1187 current status of the gen_server process.
1188 PDict is the current value of the process dictionary of the
1190 gen_server process..
1191 State is the internal state of the gen_server process.
1193 The function is to return Status, a term that changes the de‐
1195 tails of the current state and status of the gen_server process.
1196 There are no restrictions on the form Status can take, but for
1197 the sys:get_status/1,2 case (when Opt is normal), the recom‐
1198 mended form for the Status value is [{data, [{"State", Term}]}],
1199 where Term provides relevant details of the gen_server state.
1200 Following this recommendation is not required, but it makes the
1201 callback module status consistent with the rest of the
1202 sys:get_status/1,2 return value.
1203 One use for this function is to return compact alternative state
1205 representations to avoid that large state terms are printed in
1206 log files.
1207 Module:handle_call(Request, From, State) -> Result
1209 Types:
1211 Request = term()
1213 From = from()
1214 State = term()
1215 Result = {reply,Reply,NewState}
1216 | {reply,Reply,NewState,Timeout}
1217 | {reply,Reply,NewState,hibernate}
1218 | {reply,Reply,NewState,{continue,Continue}}
1219 | {noreply,NewState}
1220 | {noreply,NewState,Timeout}
1221 | {noreply,NewState,hibernate}
1222 | {noreply,NewState,{continue,Continue}}
1223 | {stop,Reason,Reply,NewState}
1224 | {stop,Reason,NewState}
1225 Reply = term()
1226 NewState = term()
1227 Timeout = timeout()
1228 Continue = term()
1229 Reason = term()
1230 Whenever a gen_server process receives a request sent using
1232 call/2,3 or multi_call/2,3,4, this function is called to handle
1233 the request.
1234 State is the internal state of the gen_server process, and New‐
1236 State a possibly updated one.
1237 Request is passed from the same argument provided to call or
1239 multi_call.
1240 The return value Result is interpreted as follows:
1242 {reply,Reply,NewState}
1244 {reply,Reply,NewState,_}: The Reply value is sent back to
1245 the client request and there becomes its return value.
1246 The gen_server process continues executing with the possibly
1248 updated internal state NewState.
1249 {noreply,NewState}
1251 {noreply,NewState,_}: The gen_server process continues exe‐
1252 cuting with the possibly updated internal state NewState.
1253 A reply to the client request has to be created by calling
1255 reply(From, Reply), either in this or in a later callback.
1256 {reply,_,_,Timeout}
1258 {noreply,_,Timeout}: If an integer Timeout is provided, a
1259 time-out occurs unless a request or a message is received
1260 within that many milliseconds. A time-out is represented by
1261 the atom timeout to be handled by the Module:handle_info/2
1262 callback function. Timeout =:= infinity can be used to wait
1263 indefinitely, which is the same as returning a value without
1264 a Timeout member.
1265 {reply,_,_,hibernate}
1267 {noreply,_,hibernate}: The process goes into hibernation
1268 waiting for the next message to arrive (by calling
1269 proc_lib:hibernate/3).
1270 {reply,_,_,{continue,Continue}}
1272 {noreply,_,{continue,Continue}}: The process will execute
1273 the Module:handle_continue/2 callback function, with Con‐
1274 tinue as the first argument.
1275 {stop,Reason,NewState}
1277 {stop,Reason,Reply,NewState}: The gen_server process will
1278 call Module:terminate(Reason,NewState) and then terminate.
1279 {stop,_,Reply,_} will create a reply to the client request
1281 just as {reply,Reply,...} while {stop,_,_} will not, so just
1282 as for {noreply,NewState,...} a reply has to be created by
1283 calling reply(From, Reply) before returning {stop,_,_}.
1284 Module:handle_cast(Request, State) -> Result
1286 Types:
1288 Request = term()
1290 State = term()
1291 Result = {noreply,NewState}
1292 | {noreply,NewState,Timeout}
1293 | {noreply,NewState,hibernate}
1294 | {noreply,NewState,{continue,Continue}}
1295 | {stop,Reason,NewState}
1296 NewState = term()
1297 Timeout = timeout()
1298 Continue = term()
1299 Reason = term()
1300 Whenever a gen_server process receives a request sent using
1302 cast/2 or abcast/2,3, this function is called to handle the re‐
1303 quest.
1304 For a description of the arguments and possible return values,
1306 see Module:handle_call/3.
1307 Module:handle_continue(Continue, State) -> Result
1309 Types:
1311 Continue = term()
1313 State = term()
1314 Result = {noreply,NewState}
1315 | {noreply,NewState,Timeout}
1316 | {noreply,NewState,hibernate}
1317 | {noreply,NewState,{continue,Continue}}
1318 | {stop,Reason,NewState}
1319 NewState = term()
1320 Timeout = timeout()
1321 Continue = term()
1322 Reason = normal | term()
1323 Note:
1325 This callback is optional, so callback modules need to export it
1326 only if they return one of the tuples containing {continue,Con‐
1327 tinue} from another callback. If such a {continue,_} tuple is
1328 used and the callback is not implemented, the process will exit
1329 with undef error.
1330 This function is called by a gen_server process whenever a pre‐
1333 vious callback returns one of the tuples containing {continue,
1334 Continue}. handle_continue/2 is invoked immediately after the
1335 previous callback, which makes it useful for performing work af‐
1336 ter initialization or for splitting the work in a callback in
1337 multiple steps, updating the process state along the way.
1338 For a description of the other arguments and possible return
1340 values, see Module:handle_call/3.
1341 Module:handle_info(Info, State) -> Result
1343 Types:
1345 Info = timeout | term()
1347 State = term()
1348 Result = {noreply,NewState}
1349 | {noreply,NewState,Timeout}
1350 | {noreply,NewState,hibernate}
1351 | {noreply,NewState,{continue,Continue}}
1352 | {stop,Reason,NewState}
1353 NewState = term()
1354 Timeout = timeout()
1355 Reason = normal | term()
1356 Note:
1358 This callback is optional, so callback modules need not export
1359 it. The gen_server module provides a default implementation of
1360 this function that logs about the unexpected Info message, drops
1361 it and returns {noreply, State}.
1362 This function is called by a gen_server process when a time-out
1365 occurs or when it receives any other message than a synchronous
1366 or asynchronous request (or a system message).
1367 Info is either the atom timeout, if a time-out has occurred, or
1369 the received message.
1370 For a description of the other arguments and possible return
1372 values, see Module:handle_call/3.
1373 Module:init(Args) -> Result
1375 Types:
1377 Args = term()
1379 Result = {ok,State}
1380 | {ok,State,Timeout}
1381 | {ok,State,hibernate}
1382 | {ok,State,{continue,Continue}}
1383 | {stop,Reason}
1384 | {error,Reason}
1385 | ignore
1386 State = term()
1387 Timeout = timeout()
1388 Reason = term()
1389 Whenever a gen_server process is started using start/3,4,
1391 start_monitor/3,4, or start_link/3,4, this function is called by
1392 the new process to initialize.
1393 Args is the Args argument provided to the start function.
1395 The return value Result is interpreted as follows:
1397 {ok,State}
1399 {ok,State,_}: Initialization was succesful and State is the
1400 internal state of the gen_server process.
1401 {ok,_,Timeout}
1403 {ok,_,hibernate}
1404 {ok,_,{continue,Continue}}: See the corresponding return
1405 values from Module:handle_call/3 for a description of this
1406 tuple member.
1407 {stop,Reason}
1409 : Initialization failed. The gen_server process exits with
1410 reason Reason.
1411 {error,Reason}
1413 ignore: Initialization failed. The gen_server process exits
1414 with reason normal.
1415 {error,Reason} was introduced in OTP 26.0.
1417 See function start_link/3,4's return value start_ret() in these
1419 different cases.
1420 Module:terminate(Reason, State)
1422 Types:
1424 Reason = normal | shutdown | {shutdown,term()} | term()
1426 State = term()
1427 Note:
1429 This callback is optional, so callback modules need not export
1430 it. The gen_server module provides a default implementation
1431 without cleanup.
1432 This function is called by a gen_server process when it is about
1435 to terminate. It is to be the opposite of Module:init/1 and do
1436 any necessary cleaning up. When it returns, the gen_server
1437 process terminates with Reason. The return value is ignored.
1438 Reason is a term denoting the stop reason and State is the in‐
1440 ternal state of the gen_server process.
1441 Reason depends on why the gen_server process is terminating. If
1443 it is because another callback function has returned a stop tu‐
1444 ple {stop,..}, Reason has the value specified in that tuple. If
1445 it is because of a failure, Reason is the error reason.
1446 If the gen_server process is part of a supervision tree and is
1448 ordered by its supervisor to terminate, this function is called
1449 with Reason=shutdown if the following conditions apply:
1450 * The gen_server process has been set to trap exit signals.
1452 * The shutdown strategy as defined in the child specification
1454 of the supervisor is an integer time-out value, not bru‐
1455 tal_kill.
1456 Even if the gen_server process is not part of a supervision
1458 tree, this function is called if it receives an 'EXIT' message
1459 from its parent. Reason is the same as in the 'EXIT' message.
1460 Otherwise, the gen_server process terminates immediately.
1462 Notice that for any other reason than normal, shutdown, or
1464 {shutdown,Term}, see stop/3, the gen_server process is assumed
1465 to terminate because of an error, and an error report is issued
1466 using logger(3).
1467 When the gen_server process exits, an exit signal with the same
1469 reason is sent to linked processes and ports.
1470
1472 gen_event(3), gen_statem(3), proc_lib(3), supervisor(3), sys(3)
1473Ericsson AB stdlib 5.1.1 gen_server(3)