Add platform support and syscall mapping docs #110
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,69 @@ | ||
|
|
||
| # Platform Support | ||
|
|
||
| Darwin platforms are binary and source stable. Linux platforms follow semantic versioning. Windows follows semantic versioning. | ||
|
|
||
| ### Windows concerns | ||
|
|
||
| Trying to perfectly unify Windows with Darwin and Linux at the API level is ultimately a futile endeavor. However, in some specific cases, Windows does have directly corresponding syscalls or near-equivalents. | ||
|
|
||
| Windows-specific details are open to reevaluation pending more Windows expertise for the project. | ||
|
|
||
|
|
||
| ## API to syscall mapping | ||
|
|
||
| ### `Errno` | ||
|
|
||
| #### Instance computed properties | ||
|
|
||
| | API | Darwin | Linux | Windows | | ||
| |:-------------------|:-----------|:-----------|:-----------| | ||
| | `description` | `strerror` | `strerror` | `strerror` | | ||
| | `debugDescription` | `strerror` | `strerror` | `strerror` | | ||
|
|
||
|
|
||
| ### `FileDescriptor` | ||
|
|
||
| #### Instance methods | ||
|
|
||
| | API | Darwin | Linux | Windows | | ||
| |:-----------------------------|:------------|:------------|:---------------------------------------------------| | ||
| | `open` | `open` | `open` | `_wsopen_s(..., _SH_DENYNO, _S_IREAD | _S_IWRITE)` | | ||
milseman marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| | `close` | `close` | `close` | `_close` | | ||
| | `seek` | `lseek` | `lseek` | `_lseeki64` | | ||
| | `read` | `read` | `read` | `_read` | | ||
| | `read(fromAbsoluteOffset:)` | `pread` | `pread` | *custom* | | ||
| | `write` | `write` | `write` | `_write` | | ||
| | `write(fromAbsoluteOffset:)` | `pwrite` | `pwrite` | *custom* | | ||
| | `duplicate` | `dup` | `dup` | `_dup` | | ||
| | `duplicate(as:)` | `dup2` | `dup2` | `_dup2` | | ||
| | `resize` | `ftruncate` | `ftruncate` | *N/A* | | ||
|
There was a problem hiding this comment. Hmm, There was a problem hiding this comment. I'm really sorry, but I have trouble understanding why this table needs to exist. I beg y'all, please let's not pretend that Windows provides a syscall interface that matches Darwin or Linux. This package really isn't supposed to be platform-independent -- each platform ought to have its own set of APIs, tailored to its own peculiarities. Let each platform shine. Let each platform have its own native interfaces. Don't force one platform to needlessly (and badly) emulate the pointless minutiae of another! Embrace & expose the differences, as faithfully as possible. Creating a set of portable APIs is a very desirable and extremely important goal; however, this package most certainly cannot fulfill that goal without losing its original reason for existence -- which was to enable native system programming without the complexities of C APIs naively imported into Swift. The question shouldn't be whether it's possible to implement something on Windows that looks kind of like There was a problem hiding this comment. Actually, this set of interfaces are meant to be nearly identical (there are some differences in the sense that some require an extra parameter or such). Windows does have a POSIX (to the letter) subsystem, so these interfaces are present. Of course, being to the letter, optional interfaces may not present. |
||
|
|
||
|
|
||
| #### Static methods | ||
|
|
||
| | API | Darwin | Linux | Windows | | ||
| |:-------|:-------|:-------|:--------| | ||
| | `pipe` | `pipe` | `pipe` | *N/A* | | ||
|
There was a problem hiding this comment. Yeah, sadly, my requests that the Windows side be added at the same time were ignored :-(. There was a problem hiding this comment. The Windows SDK is generally different enough that I think it makes sense for it to have its own code base, mostly/entirely separate from the rest of this package. I don't think one can convincingly argue that |
||
|
|
||
| <details><summary>*Windows notes*</summary> | ||
|
|
||
| Windows has custom implementations for reading from or writing to an absolute offset within a file. | ||
|
|
||
| File resizing and pipes are not available on Windows at this point. | ||
|
|
||
| </details> | ||
|
|
||
|
|
||
| ## **Types** | ||
|
|
||
| **TODO** | ||
|
|
||
| ## **Values** | ||
|
|
||
| **TODO** | ||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is this meant to cover the current state or the desired state? I think that for Windows, we should consider either
_strerror_sor_wstrerror_s. The downside is that it requires a duplicated call, one to size the buffer which the user allocates and the call to convert the string.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This covers the current state, where we will make a
Stringcopy from the pointer given to us. This is not the most performance-critical path. What's the advantage of those calls?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The advantage of the calls is avoiding the annoying warnings about deprecation. Microsoft has long been trying to push for users to migrate to APIs that are user-allocated buffers rather than static buffers and to calls that take buffer pointer and size rather than buffer pointer only. These are supposed to be more "secure" as a result (at least should help alleviate some of the buffer overruns).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ok, it doesn't seem as critical in that case since we immediately copy the contents into a new String and do not expose the static buffer pointer. Please open an issue if this is something we should still track.