Niall Douglas wrote:
The NT kernel API is exceptionally stable as any changes to it cost Microsoft and anyone who writes device drivers dearly.
Even when I worked at Microsoft (not that long ago; I left in 2014), in the teams/orgs I was in, we wouldn't even consider using any undocumented NT APIs in our code: What you're doing is brave. I'm suprised no AFIO users (if people are already using AFIO) have quoted an old post like http://blogs.msdn.com/b/oldnewthing/archive/2005/07/01/434648.aspx after seeing you use those APIs.
Before I use any NT kernel API I examine when it entered NT and if it has ever changed in any release since, with the Windows XP kernel being my minimum supported kernel.
Before I use any undocumented NT API I ask myself if I'm writing a toy application for myself. If the answer is "no" then I do not. :-) I certainly wouldn't use it in code I contribute to Boost.
The only backfire found to date is the asynchronous directory enumeration via the WOW64 layer where Microsoft has a bug in their WOW64 syscall parameter repacking code, so this only affects x86 binaries on a x64 kernel.
And there we go. I didn't even notice you already have an issue opened about it: https://github.com/BoostGSoC13/boost.afio/issues/79 - I actually think this decision is going to color people's opinions of AFIO's quality.
What your comment has made me realise is that it would make much more sense if there were a "normal persons tutorial" and an "advanced users tutorial" where the former is a nice hand holding all-portable baby steps thing, and the latter is stuff like writing distributed mutual exclusion algorithms solely via atomic append onto the filesystem like is in the current tutorial. How does that plan sound?
It's your library, and you know your target audience. I would only suggest you consider that for any given example that you have decorated with platform-specific code / conditional code to illustrate some point or the other, just make sure it passes the test that any real potential customer of AFIO is going to issue: "Could I implement what this example is trying to achieve using much less [perhaps platform-specific] code, and achieve the same level of performance?". If the answer is "no", then you have nothing to worry about. Glen