Erlang/OTP Forums
Author Message

<  Open Telecom Platform (OTP)  ~  Documenting message flows in gen_server
Mojito Sorbet
Posted: Sat Aug 14, 2010 7:40 pm Reply with quote
Joined: 20 Jul 2010 Posts: 5
I am writing a complex program using many gen_server processes. They send messages back and forth locally and across nodes. I am trying to document this behavior.

eDoc does fine at documenting individual function calls. But it sees all overloading of a function name as just a single function definition. While this is appropriate for typical list recursion functions, it fails miserably when you have a dozen different forms of "handle_cast" in a single module, each to handle a different message.

Am I missing something? For a language that is all about concurrency I would have thought the doc tools would be able to capture this aspect of a program.
Back to top View user's profile Send private message
zajda
Posted: Mon Aug 23, 2010 10:13 pm Reply with quote
User Joined: 22 Aug 2009 Posts: 83
I do not entirely understand how you use gen_server.

To reach handle_cast/call usually you have API in your gen_server. So there is good place to document a function.

How do you pass messages? Do you receive them in handle_info? If so, don't do it. Create also an API and communicate processes by function calls (and under it spawn processes if you need). Make use of addressing gen_servers by PID (I mean behind this API: gen_server:call(PID, SomeStuffForHandleCall).
Doc: http://www.erlang.org/doc/man/gen_server.html#call-3
Handle_info clauses are terrible for debugging.

To sum up, if you have API you do not document your code over handle_* clauses.
Back to top View user's profile Send private message
Mojito Sorbet
Posted: Tue Aug 24, 2010 1:11 am Reply with quote
Joined: 20 Jul 2010 Posts: 5
If I understand correctly, instead of this:
Code:
gen_server:cast( Pid, {doSomething,X,Y} )
where the handler for doSomething is in module 'b', I should write
Code:
b:doSomething( Pid, X, Y )
and then in module 'b'
Code:
doSomething( Pid, X, Y ) ->
    gen_server( Pid, {doSomething,X,Y} ).
thereby keeping the fact that a message is involved entirely within module 'b'? The Pid has to be specified in any case, because there can be a large number of processes involved.

So the documentation for the action goes on the definition of b:doSomething/3 rather than on the handler where the work actually happens?

I use 'cast' mostly, unless an answer is expected; then I use 'call'.
Back to top View user's profile Send private message
zajda
Posted: Wed Aug 25, 2010 1:14 am Reply with quote
User Joined: 22 Aug 2009 Posts: 83
yes, exactly.

handle_* functions should not be treated as
"public" (for other modules) api. I always wrap it with actual api functions. As a side effect, you benefit with place to keep doc.
Back to top View user's profile Send private message

Display posts from previous:  

All times are GMT
View next topic
View previous topic
Page 1 of 1
Erlang Forum - Trap Exit Forum Index  ~  Open Telecom Platform (OTP)
This forum is locked: you cannot post, reply to, or edit topics.

Jump to:  

You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum
You can attach files in this forum
You can download files in this forum
Hosted by Erlang Solutions    |    Powered by phpBB and NoseBleed 1.14