DavisDevelopment / haxe-sys

Asynchronous system API

Work in progress!

This is the working draft for the new asys package APIs.

• Haxe Evolution proposal
• API documentation

---

• 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 (final in 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 targets
  • eval-impl - externs for eval
  • hl-impl - implementations for HashLink
  • sys-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-impl will be added to std
• for each <target>
  • <target>-impl/<target> will be added to std/<target>
  • all other directories in <target>-impl will be added to std/<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 [e-mail]: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