Skip to content

Commit

Permalink
Basic walkthrough style document.
Browse files Browse the repository at this point in the history
  • Loading branch information
@Lukasa
Lukasa committed Oct 10, 2015
1 parent b722d14 commit 7c1273f
Showing 1 changed file with 660 additions and 0 deletions.
Loading

5 comments on commit 7c1273f

@Lukasa
Copy link
Member Author

@Lukasa Lukasa commented on 7c1273f Oct 11, 2015

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for your notes @offbyone and @alexwlchan, they're greatly appreciated! Do the two of you feel like this kind of document is useful? If so, I may aim to write some others (e.g. writing a HTTP/2 web scraper etc.).

@Lukasa
Copy link
Member Author

@Lukasa Lukasa commented on 7c1273f Oct 11, 2015

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, do you have any ideas for interesting things you might want to see built?

As another idea I had, it seems like there's interesting room to talk about design patterns using Hyper-h2 as a kind of "useful example". For example, talking about how different asynchronous design patterns work, or "here's how to use threads sensibly", or that sort of thing. Do you think there'd be value in that?

@offbyone
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For my part? Hell yes; design patterns for low level APIs are excellent documentation. Especially if you can show more than one way to use it. The thing that makes API usage hard is understanding how it interacts with processes, threads, memory, and re-use, all of which are well demonstrated by design articles.

So, 👍

@alexwlchan
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Design pattern documentation would be excellent. Examples from hyper-h2 a plus, and probably much more helpful than just trying to read the code and divine the design principles unaided. +1 to design patterns.

I'd like to find out how to get an HTTP/2 server that I can use with my web browser, because that seems like it would be a Useful Thing. [I'm aware that there are examples with twisted and asyncio, but (a) I haven't read them yet, so I may be asking for something that already exists, and (b) I have never used either of those libraries; having the hyper details pulled out separately might be nice.]

@Lukasa
Copy link
Member Author

@Lukasa Lukasa commented on 7c1273f Oct 13, 2015

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So, on the topic of "a server you can use with your browser", that turns out to be A Pain In The Ass™. The security requirements for HTTP/2 are high, which means you need a quite recent OpenSSL. Both the Twisted example and the asyncio example can do it (the Twisted one requires a Twisted patch that I haven't landed yet), but in both cases you need OpenSSL 1.0.2 or newer, which is comparatively rare.

I think it's worth documenting these requirements and what you do once you've satisfied them though.

Got suggestions for design patterns worth seeing? I can think of a few:

  • coroutines, using asyncio
  • event-driven, using Twisted
  • no-shared-memory threading
  • shared-memory threading (one threading example could use actual threads, the other could use gevent/eventlet)

Suggestions for more would be great.

Please sign in to comment.