Refactor: Isolate WinAPI declarations.

[ImJotaM]

This commit replaces the direct inclusion of <windows.h> with a minimal set of manual forward declarations.

This is a deliberate architectural change to:

• Improve Compilation Speed: Avoids parsing the notoriously large Windows header.
• Eliminate Naming Pollution: Prevents name clashes with common names like min/max which conflict with the C++ standard library.
• Enhance Encapsulation: Makes the library more self-contained by not exposing the entire Windows API.

[arun11299]

I hope this is well tested and does not cause either windows or Linux builds to fail. I do not have an environment to test this currently.

[arun11299]

Sorry, I will put this on hold. I am not a fan of declaring system information which is supposed to come from platform include files.

I understand it improves the compilation but it is at the cost of added maintenance to keep updating these declarations "in case" things change.
Having said that, I am open to hear counter arguments.

Thanks.

[ImJotaM]

Hello,

First, thank you for the detailed feedback. I understand and share your concern about the maintenance cost of manually declaring system APIs, because in most situations that would be a significant risk.

However, I believe for this specific case (the core Win32 API) this approach is not only safe but also a standard practice in high-quality C++ libraries.

On the Stability of the Win32 API

My main argument is that the core of the Windows C-style API is exceptionally stable. The function signatures and types used in this pull request (CreateProcessW, HANDLE, DWORD, etc.) have not changed in decades and are the root of the entire Windows ecosystem.

Microsoft goes to extreme lengths to ensure backward compatibility. Changing these fundamental function signatures would break millions of existing applications, which is something they actively avoid at all costs. The risk of these specific declarations becoming outdated is practically zero.

Some information about:

• Raymond Chen on API contracts - An article discussing how even bugs are sometimes kept for compatibility.

• Microsoft's own documentation on API Sets - Shows how APIs are virtualized to maintain a stable forward-facing contract even as the OS internals change.

In essence, these declarations are as stable as C's printf or POSIX's open.

The Immediate Benefits for Library Users

The trade-off for this near-zero maintenance risk is a significant improvement in the library's quality and user experience.

• Faster Compilation: Including <windows.h> is notoriously slow. It's a massive header that brings in thousands of lines of code, polluting the preprocessor and slowing down every translation unit that includes the library. For a header-only library, this is a major drawback.

• Avoiding Macro Pollution: This is the most critical benefit. <windows.h> defines a large number of common words as macros (min, max, NEAR, FAR, etc.). The min/max macros famously conflict with std::min/std::max and are a constant source of bugs in C++ projects. While users can define NOMINMAX, a library shouldn't force its users to set preprocessor definitions to avoid breaking standard C++ code.

Zero Impact on Non-Windows Builds

As you noted, platform-specific code should be well-isolated. All these declarations are wrapped in #ifdef blocks for MSVC and MinGW compilers. This means they are completely invisible to Linux and macOS builds, ensuring that there is absolutely no risk of impacting or changing the library's behavior on other platforms.

I believe these changes make the library significantly more robust, faster to compile, and easier to use for developers on Windows, without introducing a realistic maintenance burden.

Thank you again for considering my contribution.

[arun11299]

Thank you for taking time to compile such a detailed response. I am sold.

[arun11299]

@ImJotaM Can you please look into the unit tests where it is currently assuming inclusion of windows.h ? The build failed due to use of Sleep function in test_ret_code.cc

[ImJotaM]

The Sleep function is a test-only dependency, so I'll fix this by adding #include <windows.h> directly to the test_ret_code.cc. I will open another pull request for this related fix when I finish it.