Improve existing documentation on `vibe-core` asynchronous API #28

GallaFrancesco · 2019-05-11T14:43:15Z

Description

The Vibe.d framework would benefit from improved documentation regarding the usage of its asynchronous API. This could be used to integrate the existing documentation and help new users familiarize with the low-level structure of the framework.

The current vibe-core repository lacks examples regarding how to use asynchronous I/O, while the main vibe.d repository contains a great number of application-level use cases.

Some of the missing use cases which could be demonstrated through examples are:

Basic Task usage: runTask, proper callback structure, exchanging messages between Tasks through send and receive primitives. Demonstrate Task execution flow control through yield().
WorkerTasks vs Tasks: an overview of the possible use cases of worker threads vs fibers (aka green threads, aka co-routines, aka Tasks). Usage of threads for heavy duty data processing by demonstrating an implementation of the actor model vs. using Tasks to implement e.g. an asynchronous request handler.
vibe.core.sync: Demonstrate usage of TaskMutex, RecursiveTaskMutex, TaskCondition while working with data shared between Tasks.
vibe.core.concurrency primitives: explain the logic behind Future and async and provide a simple usage example.

These examples could be included in the DLang Tour or displayed in a similar fashion on the vibe.d website and should be included in the vibe-core repository, example directory.

What are rough milestones of this project?

Task usage & WorkerTask vs Task examples
vibe.core.sync examples
vibe.core.concurrency examples
Inclusion of each examples in vibe-core (providing each example as a dub project)
Inclusion of the new vibe-core module documentation to the DLang Tour and / or vibed.org, possibly leveraging https://run.dlang.io to give the possibility of editing each example and rebuild it on the fly.

How does this project help the D community?

The Vibe.d web framework provides a simple yet extremely powerful interface for asynchronous I/O which can be exploited in a broad range of situations, such as web server implementation, concurrent data processing, the event-driven programming model.

Improving the existing documentation and providing more use cases in the form of examples would surely increase the interest in it and help new users familiarize with the vibe-core API, while allowing existing contributors to spot possible inconsistencies or bugs and fix them.

Recommended skills

Familiarity with the Vibe.d web framework.
Understanding of Vibe.d concurrency model and the difference between Threads, Tasks, the message passing interface (often referred to as the actor model).