I will second the idea behind this request. (I thought I had to use dynamic-require's second argument in the summer, and after studying it for quite a while, i was happy to figure out a way around it.)
On Sep 14, 2012, at 3:17 PM, Carl Eastlund wrote: > I just tried to figure out what the second argument of dynamic-require does > when it's not a symbol, for the nth time. First of all, the current > interface -- 0, #false, and (void) as tokens for three rather arbitrary modes > of operation -- leaves much to be desired. These other modes should probably > be other functions, or one other function with flags that are more mnemonic. > > Second, the documentation of these modes is based on the technical terms > "instantiate", "visit", and "available", which I find incredibly arcane. > Even now that I have looked them up and know what they mean (I _think_), I > don't know why these particular words were chosen for the concepts they > represent. > > To the best of my understanding, "instantiate" means "allocate space for, and > run, the relative-phase 0 content of a module"; "visit" means the same thing > at relative-phase 1. Neither the terms nor their documented definitions > actually indicate this close relationship; I had to puzzle it out to realize > they are almost the same thing, essentially differing only by add1. I would > much prefer related terms, or even just one term used with a phase number. > Otherwise I'm running around with two words for what seems to be just one > concept. I'm also confused that there is no term for running module contents > at higher phases. > > The term "available" appears to mean "queued up for on-demand instantiation". > Could we perhaps just say "lazily instantiated" here or something? Again, > the word "available" here doesn't really suggest what's going on to me. > Especially because to a user, the module doesn't actually become any more > available than it was; it's only to the runtime implementation that the > module suddenly becomes "available". And I don't think Matthew's C code > reads the documentation very often. (Though that would be impressive!) > > Of course, if I've interpreted these terms incorrectly, there's a further > problem with either the explanation or my reading comprehension. > > I can certainly understand how the documentation got to this state. The > module system is incredibly complicated, and at the outset I wouldn't know > what to name anything, either. And I would imagine dynamic-require's > interface has evolved over time. Now that we've had it a while, though, I > think we can do a lot to improve the clarity of these features. I hope > someone who understands them better than I do can take a stab at it. > > Carl Eastlund > _________________________ > Racket Developers list: > http://lists.racket-lang.org/dev _________________________ Racket Developers list: http://lists.racket-lang.org/dev
