haxe-sys
haxe-sys copied to clipboard
Aurel300
Asynchronous system API
Work in progress!
This is the working draft for the new asys package APIs.
- Major features
- Status
- Target TODO
- Common TODO
- Per function notes
- Project structure
- Documentation
- Testing
- HashLink setup
- Eval setup
- Running tests
Major features
- asynchrony
- more filesystem operations
- networking
- DNS
- TCP
- UDP
- Unix/IPC
- processes
- pipes
- message passing (via extended
Serializer)
- streams
- (TODO) wrap stdin, stdout, stderr in streams
- (TODO) compatibility layer for old APIs to aid transition
Status
Current WIP is the eval implementation. HL will remain broken until eval is feature-complete.
Target TODO
| Target | Build | Binds | FS | T | Net | T | Prc | T | Note |
|---|---|---|---|---|---|---|---|---|---|
| eval | Y | P | P | P | P | P | P | P | ffi, impl, externs |
| hl | Y | Y | Y | P | N | N | N | N | ffi, impl |
| cpp | N | N | N | N | N | N | N | N | |
| js | - | - | N | N | N | N | N | N | hxnodejs only, most APIs forwarded directly |
| rest | - | N | N | N | N | N | N | N |
-
Build- can we compile the interpreter (if any) with libuv? -
Binds- is the FFI finished, or is there a good binding library available? -
FS- are the filesystem functions implemented? -
Net- are the networking (TCP, UDP, DNS) functions implemented? -
Prc- are the process functions implemented? -
T- are the tests for the previous column done? -
Y,P,N,-- yes, partially, no, not applicable -
[ ] hl, eval, cpp - use GC a bit better; automatically close
uv_file(and others?) once collected -
[ ] eval - figure out instance variables (
finalin particular) on eval types, would allow unifying e.g.sys.uv.Stat
Common TODO
These should be implemented in pure Haxe, with minimal #if <target> parts where necessary.
| Feature | Impl | T | Notes |
|---|---|---|---|
| streams | P | P | based on streams3 of Node.js; simplified interface (dropped legacy APIs) |
- [ ] stream auto-HWM balancing, piping
- [ ] compatibility layer (
sys-compat)
Per function notes
| Category | Function | Notes |
|---|---|---|
| FS | copyfile |
n/a; only in libuv >= 1.14 |
| FS | chmod with followSymlinks == false |
n/a; lchmod only in libuv >= 1.21 |
| FS | chown with followSymlinks == false |
n/a; lchown only in libuv >= 1.21 |
| FS | truncate |
emulated with open("r+"), ftruncate (see node) |
| FS | mkdir with recursive == true |
emulated |
| FS | rmdir |
??? should we have a recursive mode for rmdir |
Project structure
- implementations
common-impl- implementations common to all targetseval-impl- externs for evalhl-impl- implementations for HashLinksys-compat- compatibility layer (old APIs implemented using the new APIs)
- documentation
docs
- tests
tests- unit tests
The new sys APIs are in the asys package. Some new additions which are not sys-specific are added to the haxe pacakge. The classes in <target>-impl are expected to shadow those in common-impl, just like the existing standard library in Haxe.
Once the new APIs are ready to be merged into the standard library:
common-implwill be added tostd- for each
<target><target>-impl/<target>will be added tostd/<target>- all other directories in
<target>-implwill be added tostd/<target>/_std
Documentation
A build of the documentation is available here. It can be built manually using the docs/generate.sh script.
Testing
HashLink setup
To test the HashLink implementations, please use the feature/libuv branch of Aurel300/hashlink, which includes updated libuv FFI.
git clone [email protected]:Aurel300/hashlink.git
cd hashlink
make
make install
Eval setup
To test the Eval implementations, please use the feature/eval-libuv branch of Aurel300/haxe, which includes libuv FFI and OCaml implementations.
Running tests
cd tests
haxe build-hl.hxml && hl bin/test.hl
haxe build-eval.hxml
Aurel300