├── .github
└── workflows
│ └── main.yml
├── README.md
├── example-world.md
├── test
└── README.md
└── wit
├── poll.wit
└── world.wit
/.github/workflows/main.yml:
--------------------------------------------------------------------------------
1 | name: CI
2 | on:
3 | push:
4 | branches: [main]
5 | pull_request:
6 | branches: [main]
7 |
8 | jobs:
9 | abi-up-to-date:
10 | name: Check ABI files are up-to-date
11 | runs-on: ubuntu-latest
12 | steps:
13 | - uses: actions/checkout@v2
14 | - uses: WebAssembly/wit-abi-up-to-date@v13
15 | with:
16 | wit-abi-tag: wit-abi-0.11.0
17 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # WASI Poll
2 |
3 | This wasi-poll repository has been subsumed by [wasi-io](https://github.com/WebAssembly/wasi-io).
4 | Its contents, including the specification of the `poll-oneff` function, which has been renamed
5 | to `poll-list`, has moved there.
6 |
7 | ---
8 |
9 | A proposed [WebAssembly System Interface](https://github.com/WebAssembly/WASI) API.
10 |
11 | ### Current Phase
12 |
13 | WASI-poll is currently in [Phase 2].
14 |
15 | [Phase 2]: https://github.com/WebAssembly/WASI/blob/42fe2a3ca159011b23099c3d10b5b1d9aff2140e/docs/Proposals.md#phase-2---proposed-spec-text-available-cg--wg
16 |
17 | ### Champions
18 |
19 | - Dan Gohman
20 |
21 | ### Phase 4 Advancement Criteria
22 |
23 | WASI poll must have host implementations which can pass the testsuite
24 | on at least Windows, macOS, and Linux.
25 |
26 | WASI poll must have at least two complete independent implementations.
27 |
28 | ## Table of Contents [if the explainer is longer than one printed page]
29 |
30 | - [Introduction](#introduction)
31 | - [Goals](#goals)
32 | - [Non-goals](#non-goals)
33 | - [API walk-through](#api-walk-through)
34 | - [Use case 1](#use-case-1)
35 | - [Use case 2](#use-case-2)
36 | - [Detailed design discussion](#detailed-design-discussion)
37 | - [[Tricky design choice 1]](#tricky-design-choice-1)
38 | - [[Tricky design choice 2]](#tricky-design-choice-2)
39 | - [Considered alternatives](#considered-alternatives)
40 | - [[Alternative 1]](#alternative-1)
41 | - [[Alternative 2]](#alternative-2)
42 | - [Stakeholder Interest & Feedback](#stakeholder-interest--feedback)
43 | - [References & acknowledgements](#references--acknowledgements)
44 |
45 | ### Introduction
46 |
47 | WASI Poll is a WASI API for waiting for I/O events on multiple handles.
48 |
49 | It is similar in spirit to the POSIX `poll` function.
50 |
51 | ### Goals
52 |
53 | The primary goal of WASI Poll is to allow users to use WASI programs to
54 | be able to wait for stream read, stream write, stream error, and clock timeout
55 | events, on multiple handles.
56 |
57 | ### Non-goals
58 |
59 | WASI Poll is not yet aiming to support large numbers of handles efficiently.
60 | Future proposals will ideally add something similar to Linux's `epoll`, but
61 | that is not yet addressed.
62 |
63 | ### API walk-through
64 |
65 | [Walk through of how someone would use this API.]
66 |
67 | #### [Use case 1]
68 |
69 | [Provide example code snippets and diagrams explaining how the API would be used to solve the given problem]
70 |
71 | #### [Use case 2]
72 |
73 | [etc.]
74 |
75 | ### Detailed design discussion
76 |
77 | [This section should mostly refer to the .wit.md file that specifies the API. This section is for any discussion of the choices made in the API which don't make sense to document in the spec file itself.]
78 |
79 | ### Why is the function called `poll_oneoff`?
80 |
81 | This is referencing the fact that this function is not efficient when used
82 | repeatedly with the same large set of handles. In the future, it is expected
83 | that follow-up proposals will add a poll function which can create sets of
84 | handles that can be polled together efficiently.
85 |
86 | ### Why doesn't the return type have a way to indicate failure?
87 |
88 | `poll_oneoff` itself never fails. It may be interrupted, and there may be
89 | errors on the I/O resources referred to by the handles passed to it, but
90 | the poll isn't doing any I/O of its own, so it has no need to fail.
91 |
92 | ### Considered alternatives
93 |
94 | [This section is not required if you already covered considered alternatives in the design discussion above.]
95 |
96 | #### [Alternative 1]
97 |
98 | [Describe an alternative which was considered, and why you decided against it.]
99 |
100 | #### [Alternative 2]
101 |
102 | [etc.]
103 |
104 | ### Stakeholder Interest & Feedback
105 |
106 | TODO before entering Phase 3.
107 |
108 | [This should include a list of implementers who have expressed interest in implementing the proposal]
109 |
110 | ### References & acknowledgements
111 |
112 | Many thanks for valuable feedback and advice from:
113 |
114 | - [Person 1]
115 | - [Person 2]
116 | - [etc.]
117 |
--------------------------------------------------------------------------------
/example-world.md:
--------------------------------------------------------------------------------
1 |
2 |
9 |
10 | A poll API intended to let users wait for I/O events on multiple handles
11 | at once.
12 |
13 | Types
14 |
15 | u32
16 | A "pollable" handle.
17 |
This is conceptually represents a stream<_, _>, or in other words,
18 | a stream that one can wait on, repeatedly, but which does not itself
19 | produce any data. It's temporary scaffolding until component-model's
20 | async features are ready.
21 | And at present, it is a u32 instead of being an actual handle, until
22 | the wit-bindgen implementation of handles and resources is ready.
23 | pollable lifetimes are not automatically managed. Users must ensure
24 | that they do not outlive the resource they reference.
25 | This represents a resource.
26 |
27 | Functions
28 |
29 | Dispose of the specified pollable, after which it may no longer
30 | be used.
31 | Params
32 |
35 |
36 | Poll for completion on a set of pollables.
37 | This function takes a list of pollables, which identify I/O sources of
38 | interest, and waits until one or more of the events is ready for I/O.
39 | The result list<bool> is the same length as the argument
40 | list<pollable>, and indicates the readiness of each corresponding
41 | element in that list, with true indicating ready. A single call can
42 | return multiple true elements.
43 | A timeout can be implemented by adding a pollable from the
44 | wasi-clocks API to the list.
45 | This function does not return a result; polling in itself does not
46 | do any I/O so it doesn't fail. If any of the I/O sources identified by
47 | the pollables has an error, it is indicated by marking the source as
48 | ready in the list<bool>.
49 | The "oneoff" in the name refers to the fact that this function must do a
50 | linear scan through the entire list of subscriptions, which may be
51 | inefficient if the number is large and the same subscriptions are used
52 | many times. In the future, this is expected to be obsoleted by the
53 | component model async proposal, which will include a scalable waiting
54 | facility.
55 | Params
56 |
59 | Return values
60 |
63 |
--------------------------------------------------------------------------------
/test/README.md:
--------------------------------------------------------------------------------
1 | # Testing guidelines
2 |
3 | TK fill in testing guidelines
4 |
5 | ## Installing the tools
6 |
7 | TK fill in instructions
8 |
9 | ## Running the tests
10 |
11 | TK fill in instructions
12 |
--------------------------------------------------------------------------------
/wit/poll.wit:
--------------------------------------------------------------------------------
1 | /// A poll API intended to let users wait for I/O events on multiple handles
2 | /// at once.
3 | interface poll {
4 | /// A "pollable" handle.
5 | ///
6 | /// This is conceptually represents a `stream<_, _>`, or in other words,
7 | /// a stream that one can wait on, repeatedly, but which does not itself
8 | /// produce any data. It's temporary scaffolding until component-model's
9 | /// async features are ready.
10 | ///
11 | /// And at present, it is a `u32` instead of being an actual handle, until
12 | /// the wit-bindgen implementation of handles and resources is ready.
13 | ///
14 | /// `pollable` lifetimes are not automatically managed. Users must ensure
15 | /// that they do not outlive the resource they reference.
16 | ///
17 | /// This [represents a resource](https://github.com/WebAssembly/WASI/blob/main/docs/WitInWasi.md#Resources).
18 | type pollable = u32
19 |
20 | /// Dispose of the specified `pollable`, after which it may no longer
21 | /// be used.
22 | drop-pollable: func(this: pollable)
23 |
24 | /// Poll for completion on a set of pollables.
25 | ///
26 | /// This function takes a list of pollables, which identify I/O sources of
27 | /// interest, and waits until one or more of the events is ready for I/O.
28 | ///
29 | /// The result `list` is the same length as the argument
30 | /// `list`, and indicates the readiness of each corresponding
31 | /// element in that list, with true indicating ready. A single call can
32 | /// return multiple true elements.
33 | ///
34 | /// A timeout can be implemented by adding a pollable from the
35 | /// wasi-clocks API to the list.
36 | ///
37 | /// This function does not return a `result`; polling in itself does not
38 | /// do any I/O so it doesn't fail. If any of the I/O sources identified by
39 | /// the pollables has an error, it is indicated by marking the source as
40 | /// ready in the `list`.
41 | ///
42 | /// The "oneoff" in the name refers to the fact that this function must do a
43 | /// linear scan through the entire list of subscriptions, which may be
44 | /// inefficient if the number is large and the same subscriptions are used
45 | /// many times. In the future, this is expected to be obsoleted by the
46 | /// component model async proposal, which will include a scalable waiting
47 | /// facility.
48 | poll-oneoff: func(in: list) -> list
49 | }
50 |
--------------------------------------------------------------------------------
/wit/world.wit:
--------------------------------------------------------------------------------
1 | package wasi:poll
2 |
3 | world imports {
4 | import poll
5 | }
6 |
--------------------------------------------------------------------------------