sleep() and clock() should return az_result

[antkmsft]

We have only two functions in the PAL layer: void sleep() and int64 clock(). We should change them to az_result sleep() and az_result clock(int64* out), so that they would return AZ_ERROR_DEPENDENCY_NOT_PROVIDED, so the code catches it early and exits without possibly attempting to work, but working in a strange way. So, if your code ends up relying on these functions, and it fails, you'll get a clear error code telling about the problem, and sooner.

[ahsonkhan]

That might be optimizing the API design too much for the "failure" condition. Having the clock not return the current time hurts usability. Similarly, having sleep return something might be surprising to users.

@JeffreyRichter - what are your thoughts on this?

[RickWinter]

@ahsonkhan It feels reasonable to adopt this design pattern. I would expect this pattern on all pal APIs so we should review carefully before making the change

[JeffreyRichter]

The only code "using"/calling these functions is our code so I don't care much about the usability. These function are NOT part of our SDK's public API and so customer can't call them directly but they have no need to because they had to provide them to us in the first place.

[antkmsft]

Another possible solution proposal by Jeff: put preconditions that always fail (in az_noplatform implementation)

From myself: why don't we do the same in az_nohttp? And I think we should not be doing this in az_nohttp, because you run a sample and suddenly you have to learn preconditions, not the best possible experience, although it is not that bad. Maybe platform and http are different in this aspect - what is good for az_noplatform, doesn't work from the usability standpoint in az_nohttp.

[ahsonkhan]

These function are NOT part of our SDK's public API and so customer can't call them directly but they have no need to because they had to provide them to us in the first place.

It is the interface that we define, that the user has to implement. I would consider that as public API.

[JeffreyRichter]

Well, OK, yes the function signatures are documented (if you want to call this public) but I do not think of the functions as being part of our public SDK surface area that consumers of our SDK would call directly. The PAL functions implementations are just to get the SDK working for US.