http://www.perlmonks.org?node_id=734362


in reply to Re^7: IO::Lambda: call for participation
in thread IO::Lambda: call for participation

Of course I don't mind questions, on the contrary, I'm interested to answer as much as I can, otherwise it won't be clear to me what parts of docs are insufficiently explained. So fire away!

With sleep, and all the predicates, I see where confusion stems from. All of the predicates accepts parameters on two stacks. The callback itself is the only parameter that is passed using perl stack, and all predicates have (&) signature for exactly that. All the other parameters are passed in the context.

Back to your question, a signature of sleep. The doc says that it is "sleep($deadline)", and is correct in that regard, because it omits two facts that all predicates a) have perl signature (&) and b) always deal with callbacks, so callbacks were not mentioned too.

Thus, passing the call as &sleep($deadline) is not correct, but &sleep($_[0]) is. sleep(&) expects the callback in $_[0], and deadline in context[0]. Hope that dissolves the confusion.

Finally, predicates. It seems that the word has many notions, and can be confusing. I'll need to document that term much more thoroughly, - or even consider another name?

Replies are listed 'Best First'.
Re^9: IO::Lambda: call for participation
by xdg (Monsignor) on Jan 06, 2009 at 13:55 UTC

    How about "conditions" instead of "predicates"? Also, at the expense of changing your API, it might be clearer if the functions names themselves were less like perl functions and more intuitively descriptive.

    • read -> readable
    • write -> writeable
    • sleep -> timeout
    • etc

    My thought is that since these aren't actually executed immediately, it would be better to have names that describe the activating condition rather than names that sound like an imperative.

    For documentation, I'd strongly suggest separating the perl signature from the context arguments. E.g.

    read($callback) -- context stack: $filehandle, $deadline = undef

    -xdg

    Code written by xdg and posted on PerlMonks is public domain. It is provided as is with no warranties, express or implied, of any kind. Posted code may not have been tested. Use of posted code is at your own risk.

      Hmm.. Indeed, read() and write(), being the first predicates implemented, stemmed from classic on_read and on_write, and by doing that I deliberately walked away from the on_xxx semantics. I agree that besides being an established API, there are not many arguments against switching from read to on_read or readable. However, do you think that the other conditions should be renamed too? How about names in the neighbor modules, such as connect(), dbi_select(), dns(), etc so many? Or, let me rephrase, how important is presence of on_ in on_read? Even though I'm more inclined in converting "read" into "readable", I doubt that this can be done unambiguously for all cases, like it is with the "on_" prefix. Possibly that decision sacrificed clarity for the sake of brevity. But possibly not, I don't know really.

      As for the second advice, I agree. If the absence of perl signature causes confusion, the signature shall be added.

      On the side note, I'm thinking about all the advices given, and I see that deciphering the information compacted into the current manual could result in a fairly large article. I'm thinking to write it using a wiki or something, I don't know, I never done anything like that, so that the documentation and the module itself will be subject of discussion while being written, not postfactum. As soon as I write a first draft, I'll post it here for review.

      Again, thank you for not giving up and digging further!

      Aaargh!

      FumbleFingers managed to select the wrong radio button resulting in an unintended (and thoroughly wrong) downvote on a node which actually deserves ++ for two wise recommendations. Apologies to xdg and all other Monks.

        No worries. :-)

        -xdg

        Code written by xdg and posted on PerlMonks is public domain. It is provided as is with no warranties, express or implied, of any kind. Posted code may not have been tested. Use of posted code is at your own risk.