/haxe-sys

Asynchronous system API

Primary LanguageHaxe

Work in progress!

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

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
  • 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 git@github.com: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