Hi, 2016-08-17 19:28 GMT+02:00 Oleg Hahm <[email protected]>:
> Hey folks, > > On Mon, Aug 15, 2016 at 04:11:48PM +0200, Martine Lenders wrote: > > as promised: here is the agenda for the meeting next Wednesday: > > http://yourpart.eu/p/netapp-api-riot > > thanks for the protocol, but is a bit hard to follow as a non-attendee. > Could > anyone come up with a short summary and, in case you concluded on a > particular API, could present how it should look like? already reworked it to a more readable form (just waited for some comments by the attendees) [1] TL;DR: * reworked API will be called sock not conn to keep them distinguishable when talking about it / porting it * UDP/IP will have a somewhat reduced function set (convenience functions are dropped) * TCP will have a queue type for listening * create functions for all will receive a flags parameter so options that need to be done before binding can be passed For reference I will adapt #5533 today [1] https://github.com/RIOT-OS/RIOT/wiki/Application-Layer-API-Meeting-on-August-17,-2016 Cheers, Martine Application Layer API Meeting 1 =============================== Agenda ------ 1. Agenda Bashing 2. Goals and Priorities 3. Naming of the API 4. Detailed API-discussion: 1. IP-based transport layer with datagram-based communication (IP raw / UDP) 2. IP-based transport layer with sequence-based communication (TCP) 5. Future extension 1. Asynchronous event handling: External vs. native support 2. Options 3. Per packet configuration Meeting Details --------------- ### Attendees * Alexander Aring [eintopf] * Cenk Gündoghan * Kaspar Schleiser * Martine Lenders (Chair) * Peter Kiezmann * Simon Brummer ### Protocol * Peter * Simon Goals / Priorities ------------------ 1. No need for dynamic memory allocation 2. User friendliness 3. Simplicity 4. Efficiency (at both front- and backend) 5. Easy to implement for network stacks / portability Naming of the API ----------------- * Pro `conn: - Name was picked to differ from the old sockets because it isn't socket * Con `conn`: - `conn` basically behaves like sockets (just look at the function-calls) - New-comers might search for "something like sockets" anyway - Name change would show API change better and ultimately would be less confusing for users of `conn` * Result: `sock` as name for the new API * Side discussion: Documenting API changes - Wiki does not work, because it is forgotten after creation - Documentation via a dedicated README file is better Detailed API-discussion ----------------------- ### IP-based transport layer with datagram-based communication (IP raw / UDP) - [Reference API][conn_udp] - `sock_udp_create`/`sock_udp_close` good as is - Getter (`sock_udp_get_local`/`sock_udp_get_remote`) stay because they don't hurt and are needed for socket wrapper implementation - Setter: easier and more convenient to create new `sock` instead - `sock_udp_recv` and `sock_udp_recvfrom`: * Order of parameters of `sock_udp_recvfrom` confusing with that name * Static inline in API definition not nice * Result: + original `sock_udp_recv` should be removed + `sock_udp_recvfrom` renamed to `sock_udp_recv` - `sock_udp_send` and `sock_udp_sendto`: * There are three sensible use-cases for `sock_udp_sendto` 1. `sock != NULL`, `sock` is connected, and `remote == NULL` 2. `sock != NULL`, `sock` is connected, and `remote != NULL` 3. `sock == NULL` and `remote != NULL` * Currently only convenient function for 1., why not for 3.? * Also again: static inline in API definition * Result: + original `sock_udp_send` should be removed + `sock_udp_sendto` renamed to `sock_udp_send` ### IP-based transport layer with sequence-based communication (TCP) - [Reference API][conn_tcp] - [Simon wants a `sock_tcp_listen` function][conn_tcp_listen] - Kaspar: two object types requiered - One representing a connection, - One representing a listening socket - split `sock_tcp_create` and `sock_tcp_close`: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.c} /* Connections: * (Only port required for local; and even that only in special cases) */ sock_tcp_connect(sock_tcp_t *sock, sock_tcp_ep_t *remote, uint16_t local_port); sock_tcp_disconnect(sock_tcp_t *sock); /* Listening Socket / Queue */ sock_tcp_listen(sock_tcp_queue_t *queue, sock_tcp_ep_t *local, sock_tcp_t[] queue_array, unsigned queue_len); sock_tcp_stop_listen(sock_tcp_queue_t *queue); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - later additions: something like `tcp_listen_dynamic`, as as passing the whole queue as parameter is not suitable for servers with lots of RAM (portability) - `sock_tcp_accept` needs adaptation to new object types: `sock_tcp_accept(sock_tcp_queue_t *queue, sock_tcp_t **sock)` - rename `sock_tcp_send`/`_recv` to `sock_tcp_write`/`_read`; better suitable to semantics of streams Future extension ---------------- ### Asynchronous event handling: External vs. native support 5.1 Asynchronous event handling: External vs. native support - Callbacks due to questionable context not suitable - Additional functions for external async event handling are moved to later discussion. ### Options - getter/setter functions added later - options before bind might need additional parameters for create function - only option thinkable at the moment is something like `SO_REUSEADDR` - solvable by flag field in create function ### Per packet configuration * datagram-based stuff needs per packet configuration option (checksum, etc because 6Lo-NHC) * for now, no decision * possible solutions: - could be solved with options setting before sending - message based send as proposed in [RFC 3542][rfc3542] [conn_udp]: https://github.com/miri64/RIOT/blob/a465926c722a98bc23898c45326eb2af7c6cb9d9/sys/include/net/conn/udp.h [conn_tcp]: https://github.com/miri64/RIOT/blob/a465926c722a98bc23898c45326eb2af7c6cb9d9/sys/include/net/conn/tcp.h [conn_tcp_listen]: https://github.com/RIOT-OS/RIOT/pull/5533#issuecomment-240105485 [rfc3542]: https://tools.ietf.org/html/rfc3542#section-5
_______________________________________________ devel mailing list [email protected] https://lists.riot-os.org/mailman/listinfo/devel
