The Learning Round: Reading Docs and Extending Systems
Understand unfamiliar libraries by tracing calls, reviewing relevant documentation, and testing interpretations through small experiments. Identify documented guarantees, ambiguous rules, and potential uncertainties before making changes. Preserve existing behavior by evaluating dependencies, accounting for concurrent updates, and applying appropriate synchronization. Work through practical exercises to reinforce documentation analysis, validate assumptions, and handle uncertain system behavior safely.
We'll cover the following...
An unfamiliar library says: “Successful results are returned in input order; execution and completion order are unspecified.”
That sentence lets you predict the returned list, but not much else. Working from documentation means finding exactly where a guarantee stops, then making a small change you can defend even when tasks finish in an unexpected order.
What a guarantee does and doesn’t say
You submit J1, J2, and J3 to the library above, and all succeed. Using only that sentence, decide which prediction is warranted.
Commit an order prediction
The practice-library documentation says: “Successful results are returned in input order; execution and completion order are unspecified.”
You submit J1, J2 and J3, and all succeed. Using only this excerpt, which prediction is warranted?
The tasks begin executing in J1, J2, J3 order.
The returned results appear in J1, J2, J3 order.
Any external calls made by the tasks occur in J1, J2, J3 order.
The tasks finish in J1, J2, J3 order.
A contract is a documented promise about inputs, outputs, or behavior. “Results are returned in input order” fixes where each result appears in the list. It says nothing about which task starts first, which external call happens first, or which task finishes first. ...