Copy-edited README
This commit is contained in:
alexm-status
GitHub
parent
758388f7fc
commit
e823a52db4
78
README.md
78
README.md
|
|
@ -1,28 +1,29 @@
|
|||
# nim-asyncdispatch2
|
||||
**nim-asyncdispatch2**
|
||||
[](https://travis-ci.org/status-im/nim-asyncdispatch2) [](https://ci.appveyor.com/project/cheatfate/nim-asyncdispatch2)
|
||||
|
||||
Asyncdispatch hard fork.
|
||||
**Asyncdispatch hard fork**
|
||||
|
||||
## Core differences between asyncdispatch and asyncdispatch2.
|
||||
# Core differences between asyncdispatch and asyncdispatch2
|
||||
|
||||
1. Unified callback type `CallbackFunc`.
|
||||
Current version of asyncdispatch uses many types of callbacks.
|
||||
1. Unified callback type `CallbackFunc`:
|
||||
|
||||
* `proc ()` used in callSoon() callbacks and Future[T] completion callbacks.
|
||||
* `proc (fut: Future[T])` used in Future[T] completion callbacks.
|
||||
* `proc (fd: AsyncFD, bytesTransferred: Dword, errcode: OSErrorCode)` used in Windows IO completion callbacks.
|
||||
* `proc (fd: AsyncFD): bool` used in Unix IO events callbacks.
|
||||
Current version of asyncdispatch uses many types of callbacks:
|
||||
|
||||
Such a number of different types creates big problems in the storage, processing and interaction between callbacks. Lack of ability to pass custom user data to
|
||||
callback also creates difficulties and inefficiency, to pass custom user-defined data you need to use closures (one more allocation).
|
||||
* `proc ()` is used in callSoon() callbacks and Future[T] completion callbacks.
|
||||
* `proc (fut: Future[T])` is used in Future[T] completion callbacks.
|
||||
* `proc (fd: AsyncFD, bytesTransferred: Dword, errcode: OSErrorCode)` is used in Windows IO completion callbacks.
|
||||
* `proc (fd: AsyncFD): bool` is used in Unix IO event callbacks.
|
||||
|
||||
To resolve this issue introduced unified callback type `CallbackFunc`, which is looks like:
|
||||
Such a large number of different types creates big problems in the storage and processing of callbacks and in interaction between callbacks. Lack of ability to pass custom user data to
|
||||
a callback also creates difficulties and inefficiency with passing custom, user-defined data needed for using closures (one more allocation).
|
||||
|
||||
To resolve this issue, we have introduced a unified callback type, `CallbackFunc`:
|
||||
|
||||
```nim
|
||||
type
|
||||
CallbackFunc* = proc (arg: pointer = nil) {.gcsafe.}
|
||||
```
|
||||
Also one more type is introduced for callback storage is `AsyncCallback`.
|
||||
Also, one more type was introduced for the callback storage, `AsyncCallback`:
|
||||
|
||||
```nim
|
||||
type
|
||||
|
|
@ -31,19 +32,17 @@ Asyncdispatch hard fork.
|
|||
udata*: pointer
|
||||
```
|
||||
|
||||
2. Future[T] completion callbacks order.
|
||||
Current version of asyncdispatch processing Future[T] completion callbacks in reverse order, asyncdispatch2 schedule callbacks in forward order.
|
||||
* https://github.com/nim-lang/Nim/issues/7197
|
||||
2. The order of Future[T] completion callbacks:
|
||||
|
||||
3. Changed behavior of OS decriptor events callbacks.
|
||||
For some unknown reason current version of asyncdispatch uses seq[T] to hold list of descriptor event listeners. Actually in asynchronous environment there no need to have list of event listeners.
|
||||
Current version of asyncdispatch processes Future[T] completion callbacks in reverse order, but asyncdispatch2 schedules callbacks in forward order: https://github.com/nim-lang/Nim/issues/7197
|
||||
|
||||
So in asyncdispatch2 there only one place for one READ listener and one place for one WRITE listener.
|
||||
3. Changed the behavior of OS descriptor event callbacks:
|
||||
|
||||
4. Removed default timeout value for poll() procedure, which allows incorrect
|
||||
usage asyncdispatch and produces 500ms timeouts in correct usage.
|
||||
For some unknown reason, the current version of asyncdispatch uses seq[T] to hold a list of descriptor event listeners. However, in the asynchronous environment, there is no need for a list of event listeners. In asyncdispatch2, there is only one place for one READ listener and one place for one WRITE listener.
|
||||
|
||||
5. Changed behavior of scheduler in poll() procedure. Fixed issues:
|
||||
4. Removed the default timeout value for the poll() procedure, which allows incorrect usage of asyncdispatch and produces 500-ms timeouts in correct usage.
|
||||
|
||||
5. Changed the behavior of the scheduler in the poll() procedure, and fixed the following issues:
|
||||
* https://github.com/nim-lang/Nim/issues/7758
|
||||
* https://github.com/nim-lang/Nim/issues/7197
|
||||
* https://github.com/nim-lang/Nim/issues/7193
|
||||
|
|
@ -51,35 +50,34 @@ Asyncdispatch hard fork.
|
|||
* https://github.com/nim-lang/Nim/issues/6846
|
||||
* https://github.com/nim-lang/Nim/issues/6929
|
||||
|
||||
6. Asyncdispatch2 no longer use `epochTime()`, it uses most fastest time primitives for specific OS `fastEpochTime()`. Also because MacOS supports only millisecond resolution in `kqueue` there no need on submillisecond resolution.
|
||||
https://github.com/nim-lang/Nim/issues/3909
|
||||
|
||||
7. Removed all IO primitives `recv()`, `recvFrom()`, `connect()`, `accept()`, `send()`, `sendTo()`` from public API, and moved all it functionality into Transports.
|
||||
6. Asyncdispatch2 no longer uses `epochTime()`; instead, it uses the fastest time primitives for a specific OS, `fastEpochTime()`. Also, because MacOS supports only a millisecond resolution in `kqueue`, sub-millisecond resolution is not needed. For details, see https://github.com/nim-lang/Nim/issues/3909.
|
||||
|
||||
8. Introduced `addTimer()` / `removeTimer()` callback interface.
|
||||
7. Removed all IO primitives (`recv()`, `recvFrom()`, `connect()`, `accept()`, `send()`, and `sendTo()`) from the public API, and moved all their functionality into Transports.
|
||||
|
||||
8. Introduced an `addTimer()` / `removeTimer()` callback interface.
|
||||
|
||||
9. Introduced `removeReader()` for `addReader()` and `removeWriter()` for `addWriter()`.
|
||||
|
||||
10. Changed behavior of `addReader()`, `addWriter()`, `addTimer()` callbacks, now only explicit removal of callbacks must be supplied via (`removeReader()`, `removeWriter()`, `removeTimer()`)
|
||||
10. Changed the behavior of the `addReader()`, `addWriter()`, and `addTimer()` callbacks. Now, only the explicit removal of the callbacks must be supplied via `removeReader()`, `removeWriter()`, and `removeTimer()`.
|
||||
|
||||
11. Support cross-platform `sendfile()` operation.
|
||||
11. Added the support for the cross-platform `sendfile()` operation.
|
||||
|
||||
12. Removed expensive `AsyncEvent`, also removed support of hardware timers and ``addProcess``. (``addProcess`` will be implement as SubprocessTransport, while hardware based `AsyncEvent` will be renamed to ``ThreadAsyncEvent``).
|
||||
12. Removed the expensive `AsyncEvent` and the support for hardware timers and `addProcess`. `addProcess` will be implemented as SubprocessTransport, while hardware-based `AsyncEvent` will be renamed to `ThreadAsyncEvent`.
|
||||
|
||||
13. Added cheap synchronization primitives `AsyncLock`, `AsyncEvent`, `AsyncQueue[T]`.
|
||||
13. Added cheap synchronization primitives: `AsyncLock`, `AsyncEvent`, and `AsyncQueue[T]`.
|
||||
|
||||
## Transport concept.
|
||||
# Transport Concept
|
||||
|
||||
Transports are high level interface for interaction with OS IO system.
|
||||
The main task that the Transport concept is designed to solve is reduce number of syscalls and number of memory allocations to perform single IO operation. Current version of asyncdispatch uses at least 4 syscalls for every single IO operation:
|
||||
Transports are high-level interfaces for interaction with the OS IO system. The main task that the Transport concept is designed to solve is to reduce the number of syscalls and of memory allocations for performing a single IO operation. Current version of asyncdispatch uses at least four (4) syscalls for every single IO operation.
|
||||
|
||||
For Posix compliant systems current version of asyncdispatch performs such operations for every single IO operation:
|
||||
For Posix-compliant systems, current version of asyncdispatch performs such operations for every single IO operation:
|
||||
|
||||
- register for read/write event in system queue
|
||||
- wait for event in system queue
|
||||
- perform IO operation
|
||||
- unregister read/write event from system queue
|
||||
- Register for a read/write event in the system queue
|
||||
- Wait for an event in the system queue
|
||||
- Perform an IO operation
|
||||
- Unregister a read/write event from the system queue
|
||||
|
||||
For Windows system current version of asyncdispatch performs allocations of OVERLAPPED structure for every single IO operation.
|
||||
For Windows system, the current version of asyncdispatch performs allocations of OVERLAPPED structure for every single IO operation.
|
||||
|
||||
In order to successfully cope with the task Transport also needs to incorporate some `asyncnet.nim` functionality (e.g. buffering) for stream transports. So asyncdispatch2 has buffering IO by default.
|
||||
To successfully cope with the task, Transport also needs to incorporate some `asyncnet.nim` functionality (e.g. buffering) for stream transports. For this reason, asyncdispatch2 has buffering IO by default.
|
||||
|
|
|
|||
Loading…
Reference in New Issue