Rename start/stop to resume/suspend

[gtaban]

Rename start/stop to resume/suspend to match what GCD and Cocoa are doing.
Affects:
HTTPServing protocol
HTTPServer class
PoCSocketSimpleServer

[helje5]

This looks weird without having PR 81 first: #81

And now I'm wondering whether suspend is the same as stop. suspend would probably still have the socket open (which may fill up to the listen queue), while stop might actually close the socket.

[gtaban]

This PR would be blocked by #81
@carlbrown any thoughts on the renaming?

[carlbrown]

I agree with @helje5 - #81 should happen first, and if it doesn't happen, this shouldn't, either.

[gtaban]

ok I mistyped - I meant to say I agree that this PR is blocked by #81 for it to make sense.
Assuming #81 goes through, what are your thoughts on the renaming? @carlbrown

[seabaylea]

I think we need to consider what we want the lifecycle to be, and whether following Dispatch is the right approach for a server.

Dispatch queues have the following:

• init: creates the queue, enabling work to be added, but is suspended.
• resume: starts processing work on the queue
• suspend: stops processing work on the queue
• deallocate: shutdown the queue, running a finaliser function if provided

which I'm not convinced makes necessarily sense for a server. To be

I think the following are the likely possible events in the lifecycle:

• init: creates the server and starts it to accept and process work
• suspend: continues to accept work but doesn't process
• resume: resumes from suspend
• stop: stops the server, shuts down the port
• start: starts the server, opens the port
• shutdown: completely shutdown and destroy the server

Which of these do we think makes sense to have?

On a separate note, today if you call start() and then stop() immediately it results in a crash so we can't simply rename start/stop to resume/suspend.

[helje5]

When suggesting resume, I wasn't thinking of Dispatch, but of URLSessionTask's resume() method. Due to this Cocoa devs are familiar with that pattern (setup everything, then call resume to invoke it). I don't think resume/suspend is actually used a lot w/ Dispatch.
BTW: this uses cancel for stop/abort. Sounds reasonable to me too.

I also thought about this, but I'm against starting actual work in init. Quite often you want to wire up more stuff (make sure database connections are up, etc) before actually kicking of the stack. init should just configure the server.

Also keep in mind that the server might be running on a device, so you need to suspend/resume it when going to the background (which btw could assign new kernel assigned ports when going foreground again!).

P.S.: I don't get the thing about the start-stop crash, what does it have to do w/ the naming? start+stop shouldn't crash, neither should resume+suspend :->

[seabaylea]

P.S.: I don't get the thing about the start-stop crash, what does it have to do w/ the naming? start+stop shouldn't crash, neither should resume+suspend :->

It was an aside that really says that if we added a test as part of the PR for stop/start (or suspend/resume naming of the current APIs) it would crash - so theres more work to do than just naming.

Would this be the set that we'd ideally want?

• init: sets up the server only
• suspend: continues to accept work but doesn't process
• resume: resumes from suspend, starts the server if not already started.
• cancel: completely shutdown and destroy the server

[helje5]

I'm wondering whether we need some extra support for iOS back/foreground handling (you need to close the listen sockets and reopen them when going back to foreground). Or would we want the dev to restart the server from scratch? But then all connections would always die.

I guess it could also be automatic by listening to the notifications (but then you loose control when that happens, which might be important to the app).

[gtaban]

@seabaylea I don't understand what continues to accept work but doesn't process means. Has the server started at this time? Is it listening and accepting connections?

Additional question is, do the following lifecycle make sense?

• init
• start
• stop
• start
• stop
• shutdown

Once we clarify the lifecycle of the server, we will make sure we have appropriate tests for them.

[gtaban]

Btw if the lifecycle of the server has not been decided on, I can open a new issue to track that. Thoughts @carlbrown @seabaylea @helje5 ?

[helje5]

I think this could evolve into the issue tracking the lifecycle. (and the names would be just a result of this)

I don't understand what continues to accept work but doesn't process means

The socket would still be open, bound and listening, but not calling accept(). That will work until the kernel listen queue is full. I'm not entirely sure whether that is useful or not.

For iOS, apps really need to close when going bg and completely reopen listen socks when going fg (unless you have special VoIP like blessing, in that mode the kernel will ensure the listen sockets stay alive - which may or may not be another thing we would want to support).

[carlbrown]

Going to defer this one and see if it's still needed after #96

[helje5]

We still need to decide on lifecycle and naming, I'd reopen this one. #96 doesn't change much on the surface of the API (apart from the queue argument).

[gtaban]

Opened #98 to track the discussions about server lifecycle.