Talk:Runtime Aspects of APIs

From APIDesign

Done: bb7047d0a4d0 - I think Andrei found very important problem: The system that breaks one of the conditions for deadlock is deadlock-proof system not deadlock-prone system, forgive poor non-native speaker...

"Thread safe" may be an insufficient description for an API guarded by a coarse-grained lock such as the NetBeans Java API.

Page 177, para -2, -3: "Javadoc" instead of "JavaDoc".

Page 179, para 1: "defining a synchronized method" should be "defining a synchronized instance method".

--AndreiBadea 12:27, 9 April 2008 (UTC)

The logging tricks (The NbJUnit code) and the use of INSANE are rather NB-specific, without any mention of whether/how readers can use these tools in their own projects.

--RichUnger 22:40, 10 April 2008 (UTC)

• Page 177: The documentation for NetBeans' own APIs don't always document the threading model either.
• Page 188: The method of binding to an unused port and then writing the port number to a file is duplicated from a previous chapter.
• Page 189: The API is commonly called "SendOpts" but [is officially called the Command Line Parsing API|http://bits.netbeans.org/dev/javadoc/], so using the unofficial name will make it harder for people interested in this API to find it.
• Page 195: I don't understand the class name 'Parael'; it just looks like a misspelling of Parallel, although you did at least use it consistently.
• Page 197: "And this behaves more or less deterministically." How can something be "more or less" deterministic? It either is deterministic or it is not.

--TomWheeler Sun Apr 13 16:49:16 CDT 2008

Page 180, bottom code example: LOCK should be lock.

Page 181, code example: parameter <t>c</tt> of setCounter should be newCounter or counter.

Page 181, para 4: drop the Google search. If you really want to quote, quote a technical writing on concurrent programming.

Page 181, para -2: doesn't the code need to break all four conditions in order for the system to be prone to deadlocks?

Page 182, top code example: the type of allCreated should be Set -- program against the interface, not implementation.

Page 183, para -3: "enclose code, pass to FS library, change the files" -- you should make it clear that you enclose the code which modified the files in a runnable. Something like "You enclose the code which modifies files in a runnable and pass it for execution to the FS library. The runnable is executed in the current thread, and it is guaranteed that no file change events will be delivered during the execution.".

Page 184, para 2: "you need to perform a few tricks with synchronization". Which tricks? Suggest either giving enough details or removing this sentence.

Page 185: the DataObject example is hard to understand even for NetBeans developers who understand DataObjects, Nodes, Children.MUTEX, etc.

Page 187, code example: what is LabelProvider?

Page 187, para -1: the example description is unclear. "We start another thread" -- you don't seem to: one is the JUnit thread, another is the AWT event dispatching thread. Moreover, I'm not convinced this is a valid example: are you allowed to call createLabel in another thread that the EDT?

Page 195, para 2: so beauty does have some value after all...

--AndreiBadea 14:59, 14 April 2008 (UTC)

Done: c7fdccf6ac6d

• Page 201: In the second code listing, what type is "cnt"? This variable is never declared AFAIK. And by the way, it's a bad choice for a variable name as it is only one missing letter away from being a very naughty word!

--TomWheeler Sun Apr 13 16:49:16 CDT 2008

Page 200, top code example: the code calls doCriticalSection, but in the explanation you talk about doSomeWork.

Page 201, top code example: it is completely incomprehensible to me.

--AndreiBadea 15:05, 14 April 2008 (UTC)

• Page 204: In paragraph 2 you introduce a new term "inversion of references" while in the next paragraph you write "injection of references." It seemed like you meant the same thing in both cases so the term should be used consistently.

--TomWheeler Sun Apr 13 16:49:16 CDT 2008

No. Once it is really inject and as soon as you inject a reference, it is reversed, goes from the API to your code.