Use Case: Async IO

All programming happens synchronously (i.e. one instruction to the next). This occurs within the event loop of the main SDK execution thread. This use case will provide the ability to chunk work within this main event loop along with scheduling work within a background event loop thread.

Table of Contents

• FUNCTIONAL DECOMPOSITION
  • Start / End Timer
  • Run Task
  • Queue Task
• DESIGN NOTES
• TEST NOTES
  • Functional Demonstration
  • Unit Testing
• REFERENCES

FUNCTIONAL DECOMPOSITION

Start / End Timer

Description: An application usually has a repeating task. This task is executed on a repeating interval. It is stopped when commanded to stop. No values are returned via this task. It is simple meant to drive something on a repeating interval.

Acceptance Criteria:

1. The async namespace will provide the ability to start a repeating task on a specified millisecond interval.
2. The async namespace will provide the ability to stop a repeating task based on the repeating task id.

Run Task

Description: An application may need to run a task that does not execute synchronously. This task will run the task and if necessary, return a value from its execution. It is a one off run task. This will either carve up the main thread's execution or run in the background depending on the runtime SDK target.

Acceptance Criteria:

1. The async namespace will provide the ability to run an asynchronous task with data at a specified time in the future receiving a promise to fulfill the answer.
2. The returned promise will result either in the calculated answer or a reason for failure.

Queue Task

Description: A thread pool provides the ability to spin up a series of FIFO queue background workers. As you queue tasks, they are queued up in the order received. When a task is completed, it is reported back to the application with any calculated results.

Acceptance Criteria:

1. The async namespace will provide the ability to start a thread pool of First in First Out (FIFO) queue background workers based on the available number of CPUs.
2. The async namespace will provide the ability to queue up tasks for background processing based on a specified id and data to run with the task.
3. The async namespace will provide the calculated result via callback identifying the result via the id specified with the queued request.
4. The async namespace will provide the ability to stop the thread pool.

DESIGN NOTES

TEST NOTES

Functional Demonstration

• When an example usage is documented in the module generated documentation.
• When the module SDK details specific to each module target is documented.
• When a unit test (if applicable) specific to each module passes all tests.

Unit Testing

• Flutter Module: The test/codemelted_async_test.dart defines the unit tests for the Async I/O unit test implementation.
• JavaScript Module: Broken into the three areas:
  • codemelted_test.ts: Deno runtime tests with coverage.
  • codemelted_test.html: Mocha / Chai browser based tests executed from the PWA.
  • codemelted_worker_test.js: Background worker to ensure codemelted.js modules ability to properly load in a web worker.
• PowerShell Module: TBD
• C/C++ Module: TBD

REFERENCES

CPP Reference contributors. (2023, October 24). std::thread. In C++ Concurrency support library. Retrieved 20:53, September 13, 2024, from https://en.cppreference.com/w/cpp/thread/thread

Dart contributors. (2024, August 4). Asynchronous programming: futures, async, await. In dart.dev Libraries. Retrieved 21:00, September 13, 2024, from https://dart.dev/libraries/async/async-await

MDN contributors. (2024, July 24). Worker. In Web Workers API. Retrieved 20:51, September 13, 2024, from https://developer.mozilla.org/en-US/docs/Web/API/Worker

Microsoft Learn contributors. (n.d.). Start-ThreadJob. In PowerShell 7.4 (LTS) Reference: ThreadJob. Retrieved 21:01, September 13, 2024, from https://learn.microsoft.com/en-us/powershell/module/threadjob/start-threadjob?view=powershell-7.4

Wikipedia contributors. (2023, February 11). Thread pool. In Wikipedia, The Free Encyclopedia. Retrieved 00:24, September 13, 2024, from https://en.wikipedia.org/w/index.php?title=Thread_pool&oldid=1138829275