├── .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 |

World example-world

2 | 9 |

Import interface wasi:poll/poll

10 |

A poll API intended to let users wait for I/O events on multiple handles 11 | at once.

12 |
13 |

Types

14 |

type pollable

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 |

drop-pollable: func

29 |

Dispose of the specified pollable, after which it may no longer 30 | be used.

31 |
Params
32 | 35 |

poll-oneoff: func

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 | --------------------------------------------------------------------------------