Asynchronous IO API

.vscode/settings.json

@@ -28,5 +28,8 @@
 			],
 			"url": "./.vscode/schemas/meta.schema.json"
 		}
+	],
+	"haxe.configurations": [
+		["--cwd", "tests/asys", "build.hxml"]
 	]
 }

src/macro/eval/evalHash.ml

@@ -143,14 +143,12 @@ let key_sys_net_Lock = hash "sys.thread.Lock"
 let key_sys_net_Tls = hash "sys.thread.Tls"
 let key_sys_net_Deque = hash "sys.thread.Deque"
 let key_sys_thread_EventLoop = hash "sys.thread.EventLoop"
-
 let key_mbedtls_Config = hash "mbedtls.Config"
 let key_mbedtls_CtrDrbg = hash "mbedtls.CtrDrbg"
 let key_mbedtls_Entropy = hash "mbedtls.Entropy"
 let key_mbedtls_PkContext = hash "mbedtls.PkContext"
 let key_mbedtls_Ssl = hash "mbedtls.Ssl"
 let key_mbedtls_X509Crt = hash "mbedtls.X509Crt"
-
 let key_eval_luv_Result = hash "eval.luv.Result"
 let key_eval_luv_LuvException = hash "eval.luv.LuvException"
 let key_eval_luv_ReceiveHandle = hash "eval.luv.ReceiveHandle"

std/asys/native/IDuplex.hx

@@ -0,0 +1,11 @@
+package asys.native;
+
+import haxe.NoData;
+import haxe.io.Bytes;
+
+/**
+	An interface to read and write bytes.
+	If a class has to implement both `IReadable` and `IWritable` it is strongly
+	recommended to implement `IDuplex` instead.
+**/
+interface IDuplex extends IReadable extends IWritable {}

std/asys/native/IReadable.hx

@@ -0,0 +1,22 @@
+package asys.native;
+
+import haxe.NoData;
+import haxe.io.Bytes;
+import haxe.Exception;
+import haxe.Callback;
+
+/**
+	An interface to read bytes from a source of bytes.
+**/
+interface IReadable {
+	/**
+		Read up to `length` bytes and write them into `buffer` starting from `offset`
+		position in `buffer`, then invoke `callback` with the amount of bytes read.
+	**/
+	function read(buffer:Bytes, offset:Int, length:Int, callback:Callback<Exception,Int>):Void;
+
+	/**
+		Close this stream.
+	**/
+	function close(callback:Callback<Exception,NoData>):Void;
+}

std/asys/native/IWritable.hx

@@ -0,0 +1,27 @@
+package asys.native;
+
+import haxe.NoData;
+import haxe.io.Bytes;
+import haxe.Exception;
+import haxe.Callback;
+
+/**
+	An interface to write bytes into an out-going stream of bytes.
+**/
+interface IWritable {
+	/**
+		Write up to `length` bytes from `buffer` (starting from buffer `offset`),
+		then invoke `callback` with the amount of bytes written.
+	**/
+	function write(buffer:Bytes, offset:Int, length:Int, callback:Callback<Exception,Int>):Void;
+
+	/**
+		Force all buffered data to be committed.
+	**/
+	function flush(callback:Callback<Exception,NoData>):Void;
+
+	/**
+		Close this stream.
+	**/
+	function close(callback:Callback<Exception,NoData>):Void;
+}

std/asys/native/IoErrorType.hx

@@ -0,0 +1,80 @@
+package asys.native;
+
+/**
+	Error types.
+
+	TODO: add more error types
+**/
+@:using(asys.native.IoErrorType.IoErrorTypeTools)
+enum IoErrorType {
+	/** File or directory not found */
+	FileNotFound;
+	/** File or directory already exist */
+	FileExists;
+	/** No such process */
+	ProcessNotFound;
+	/** Permission denied */
+	AccessDenied;
+	/** The given path was not a directory as expected */
+	NotDirectory;
+	/** The given path is a directory, but a file was expected */
+	IsDirectory;
+	/** Too many open files */
+	TooManyOpenFiles;
+	/** Broken pipe */
+	BrokenPipe;
+	/** Directory not empty */
+	NotEmpty;
+	/** Requested address is not available */
+	AddressNotAvailable;
+	/** Connection reset by peer */
+	ConnectionReset;
+	/** Operation timed out */
+	TimedOut;
+	/** Connection refused */
+	ConnectionRefused;
+	/** Bad file descriptor */
+	BadFile;
+	/** Any other error */
+	CustomError(message:String);
+}
+
+class IoErrorTypeTools {
+	/**
+		Error type description
+	**/
+	static public function toString(type:IoErrorType):String {
+		return switch type {
+			case FileNotFound:
+				"File or directory not found";
+			case FileExists:
+				"File or directory already exists";
+			case ProcessNotFound:
+				"No such process";
+			case AccessDenied:
+				"Permission denied";
+			case NotDirectory:
+				"The given path was not a directory as expected";
+			case IsDirectory:
+				"The given path is a directory, but a file was expected";
+			case TooManyOpenFiles:
+				"Too many open files";
+			case BrokenPipe:
+				"Broken pipe";
+			case NotEmpty:
+				"Directory not empty";
+			case AddressNotAvailable:
+				"Address already in use";
+			case ConnectionReset:
+				"Connection reset by peer";
+			case TimedOut:
+				"Operation timed out";
+			case ConnectionRefused:
+				"Connection refused";
+			case BadFile:
+				"Bad file descriptor";
+			case CustomError(message):
+				message;
+		}
+	}
+}

std/asys/native/IoException.hx

@@ -0,0 +1,16 @@
+package asys.native;
+
+import asys.native.IoErrorType;
+import haxe.Exception;
+
+class IoException extends Exception {
+	/**
+		Error type
+	**/
+	public final type:IoErrorType;
+
+	public function new(type:IoErrorType, ?previous:Exception) {
+		super(type.toString(), previous);
+		this.type = type;
+	}
+}

std/asys/native/Stream.hx

@@ -0,0 +1,17 @@
+package asys.native;
+
+import asys.native.IDuplex;
+import asys.native.IReadable;
+import asys.native.IWritable;
+
+/**
+	Enum which is used to stay type-safe when a stream can be of any type.
+**/
+enum Stream {
+	/** Read-only stream. */
+	Read(stream:IReadable);
+	/** Write-only stream. */
+	Write(stream:IWritable);
+	/** The stream is both readable and writable. */
+	ReadWrite(stream:IDuplex);
+}

std/asys/native/filesystem/Callback.hx

@@ -0,0 +1,4 @@
+package asys.native.filesystem;
+
+//TODO: remove after https://github.com/HaxeFoundation/haxe-evolution/pull/50 is implemented
+typedef Callback<R> = haxe.Callback<haxe.Exception,R>;

std/asys/native/filesystem/Directory.hx

@@ -0,0 +1,38 @@
+package asys.native.filesystem;
+
+import haxe.NoData;
+import haxe.exceptions.NotImplementedException;
+
+/**
+	Represents a directory.
+**/
+@:coreApi
+class Directory {
+	/** The path of this directory as it was at the moment of opening the directory */
+	public final path:FilePath;
+
+	function new() {
+		path = 'stub';
+	}
+
+	/**
+		Read next batch of directory entries.
+		Passes an empty array to `callback` if no more entries left to read.
+		Ignores `.` and `..` entries.
+
+		The size of the array is always equal to or less than `maxBatchSize` value used
+		for opening this directory.
+
+		@see asys.native.filesystem.FileSystem.openDirectory
+	**/
+	public function next(callback:Callback<Array<FilePath>>):Void {
+		throw new NotImplementedException();
+	}
+
+	/**
+		Close the directory.
+	**/
+	public function close(callback:Callback<NoData>):Void {
+		throw new NotImplementedException();
+	}
+}

std/asys/native/filesystem/File.hx

@@ -0,0 +1,136 @@
+package asys.native.filesystem;
+
+import haxe.Int64;
+import haxe.io.Bytes;
+import haxe.NoData;
+import haxe.exceptions.NotImplementedException;
+import asys.native.system.SystemUser;
+import asys.native.system.SystemGroup;
+
+/**
+	TODO:
+	Add methods for reading/writing `String` data because it may be more efficient
+	on some targets (lua) than reading/writing `haxe.io.Bytes`
+**/
+@:coreApi
+class File {
+	/** The path of this file as it was at the moment of opening the file **/
+	public final path:FilePath;
+
+	function new():Void {
+		path = 'stub';
+	}
+
+	/**
+		Write up to `length` bytes from `buffer` starting at the buffer `offset`
+		to the file starting at the file `position`, then invoke `callback` with
+		the amount of bytes written.
+
+		If `position` is greater than the file size then the file will be grown
+		to the required size with the zero bytes before writing.
+
+		If `position` is negative or `offset` is outside of `buffer` bounds or
+		if `length` is negative, an error is passed to the `callback`.
+	**/
+	public function write(position:Int64, buffer:Bytes, offset:Int, length:Int, callback:Callback<Int>):Void {
+		throw new NotImplementedException();
+	}
+
+	/**
+		Read up to `length` bytes from the file `position` and write them into
+		`buffer` starting at `offset` position in `buffer`, then invoke `callback`
+		with the amount of bytes read.
+
+		If `position` is greater or equal to the file size at the moment of reading
+		then `0` is passed to the `callback` and `buffer` is unaffected.
+
+		If `position` is negative or `offset` is outside of `buffer` bounds, an
+		error is passed to the `callback`.
+	**/
+	public function read(position:Int64, buffer:Bytes, offset:Int, length:Int, callback:Callback<Int>):Void {
+		throw new NotImplementedException();
+	}
+
+	/**
+		Force all buffered data to be written to disk.
+	**/
+	public function flush(callback:Callback<NoData>):Void {
+		throw new NotImplementedException();
+	}
+
+	/**
+		Get file status information.
+	**/
+	public function info(callback:Callback<FileInfo>):Void {
+		throw new NotImplementedException();
+	}
+
+	/**
+		Set file permissions.
+	**/
+	public function setPermissions(permissions:FilePermissions, callback:Callback<NoData>):Void {
+		throw new NotImplementedException();
+	}
+
+	/**
+		Set file owner and group.
+	**/
+	public function setOwner(user:SystemUser, group:SystemGroup, callback:Callback<NoData>):Void {
+		throw new NotImplementedException();
+	}
+
+	/**
+		Shrink or expand the file to `newSize` bytes.
+
+		If the file is larger than `newSize`, the extra data is lost.
+		If the file is shorter, zero bytes are used to fill the added length.
+	**/
+	public function resize(newSize:Int, callback:Callback<NoData>):Void {
+		throw new NotImplementedException();
+	}
+
+	/**
+		Change access and modification times of the file.
+
+		TODO: Decide on type for `accessTime` and `modificationTime` - see TODO in `asys.native.filesystem.FileInfo.FileStat`
+	**/
+	public function setTimes(accessTime:Int, modificationTime:Int, callback:Callback<NoData>):Void {
+		throw new NotImplementedException();
+	}
+
+	/**
+		TODO: this requires a separate work for design and implementation
+		to find a solid cross-platform solution.
+
+		Acquire or release a file lock for the current process.
+
+		The `callback` is supplied with `true` if a lock was successfully acquired.
+
+		Modes:
+		- `Shared` - acquire a shared lock (usually used for reading)
+		- `Exclusive` - acquire an exclusive lock (usually used for writing)
+		- `Unlock` - release a lock.
+
+		By default (`wait` is `true`) `lock` waits until a lock can be acquired.
+		Pass `false` to `wait` to invoke `callback` with `false` if a lock cannot
+		be acquired immediately.
+
+		Although a lock may be released automatically on file closing, for a
+		consistent cross-platform behavior it is strongly recommended to always
+		release a lock manually.
+
+		This lock is _not_ suitable for controlling access to a file by multiple threads.
+	**/
+	// public function lock(mode:FileLock = Exclusive, wait:Bool = true, callback:Callback<Bool>):Void {
+	// 	throw new NotImplementedException();
+	// }
+
+	/**
+		Close the file.
+
+		Does not fail if the file is already closed.
+	**/
+	public function close(callback:Callback<NoData>):Void {
+		throw new NotImplementedException();
+	}
+}