Comment by shakna
6 years ago
> What else exactly do you need?
What unit it reflects. What epoch it uses. When does it wraparound? Is it realtime? Or best guess? Is it wall-clock like CLOCK_REALTIME or is closer to CLOCK_MONOTONIC? Is a valid range the entirety of possible uint64 values, or is there a range limit?
The answer is “not applicable” to all of these. The word clock is unit less, just ticking up each sample. It’s not actually a clock in the normal sense, there is no leap years or anything in it. It’s used to synchronize devices.
Granted, the documentation isn’t the best at explaining it. But if you know what a word clock is in terms of audio, you know what the value is; a counter.
> The word clock is unit less, just ticking up each sample.
That should be in the documentation. Each sample is guaranteed to have an increment compared to a previous sample.
But, it doesn't answer all of the questions.
Does the world clock always start from 0? Is that an assumption that can be made?
Or is the valid range anywhere inside a uint64?
What happens if the number of samples exceeds the length of the world clock unit? Is it allowed to overflow? In which case it violates the assumption that it always just increments.
Even if it counts in picoseconds it’ll take several centuries to roll-over, so these probably aren’t questions you ever need to ask. Though that’s kind of the point: the API and its documentation should highlight the stuff you need to worry about, such as where you get these values from and what they do, and hide everything else that you don’t (internal implementation details).
But that particular API does the opposite. Just typedef-ing that data as an opaque `WordClockTime_t` would go a long way to fixing this, telling API users to ignore how it works internally and enabling automated documentation tools to to locate and list every other API that produces/consumes this particular value. A simple automation-friendly abstraction that would reduce—if not eliminate—the need for additional manually-written documentation. i.e. Put the knowledge in the code and the automation can graph it.
Alas, there’s something about C programming that seems to bring out the worst abstractions in many C programmers… and if they’re being lazy in their API design, they’ll be twice as lazy when it comes to manually documenting it.
--
"What is wrong with giving tree, here?"
"Well, he don't know talking good like me and you, so his vocabulistics is limited to 'I' and 'am' and 'Groot.' Exclusively, in that order."
4 replies →
There is a glossary in the CoreAudio docs, but it hasn't been updated since 2010. And it doesn't include an entry for WordClock.
You could argue that generally the docs are good enough to Get Shit Done. And people are Getting Shit Done on the platform as a whole. So there's no problem.
But it's a shame Apple doesn't consider better docs a priority. IMO it's not a good look for a trillion dollar company.
More, I don't know if insiders use the same doc base. If so it's definitely wasteful, because newcomers are going to be wasting time and effort trying to get up to speed.