Discussion: API Changes for Hopac 1.0

[neoeinstein]

I'd like to push toward a stable 1.0 API for Hopac. Much of the API looks good and is relatively stable, but there may be some changes that we can make before a 1.0 release that can improve the usability of the API. Below are a couple of my ideas.

• Rollback use of constructors for Promises and IVar and some others, preferring create/createFull/createFailed functions.

• The idea of removing Scheduler from the design has been previously discussed. I am not sure quite where to start to do this, but it may be better to reserve for a possible 2.0.

• Move away from functional jargon names or add functions that have more names that are more "friendly" to new users. Taking a page from Elm, possibly introduce andThen as a synonym for bind.

• It is too easy to use Alt.prepare incorrectly, often doing synchronous work (or worse, waiting on jobs synchronously) before returning the Alt. Instead users that need to do asynchronouse work before an Alt is ready should be creating a Promise (through memo, for example) so that the Alt can finish instantiation and then continue to instantiate other Alts in a choose block. Possibly add documentation to the various Alt functions and/or add other functions into Alt that provide the intended functionality (even if simple synonyms to existing functions).

• Harmonize the names of Job/Alt/Promise functions that return unit, a constant, an exception, and that never return.

Each of these and more may spawn additional tickets, but I wanted to get some feedback before I go running off with this.

[haf]

andThen could just be an alias – in that case +1.

I agree with deferring the scheduler to v2

[nestordemeure]

Hello, I am speaking as a potential user : I have not used Hopac but I read all the documentation I could find to grasp the project (I just don't have a use case currently).

Move away from functional jargon names or add functions that have more names that are more "friendly" to new users. Taking a page from Elm, possibly introduce andThen as a synonym for bind.

It would clearly lower the barrier of entry (at last for me : an F#_but_never_Haskell developer :) )

[21c-HK]

The idea of removing Scheduler from the design has been previously discussed. I am not sure quite where to start to do this, but it may be better to reserve for a possible 2.0.

What are the reasons for wanting to removing the Scheduler from the design? Or could you please link to the discussion if it is too complicated to summarize?

Move away from functional jargon names or add functions that have more names that are more "friendly" to new users. Taking a page from Elm, possibly introduce andThen as a synonym for bind.

I agree. bind could also be called continue_with and result could be called from_value. There should also be different names for IVar and MVar, which may be confused with the types of the same name in Haskell (at least I have seen them only in Haskell code), especially since MVar in Hopac has different semantics than MVar in Haskell (according to the reference). Why is it called MVar if the description only refers to a ‘serialized variable’? The M stands for ‘mutable’ in Haskell and the I stands for ‘immutable’ in Haskell.

It also would not hurt if the types and functions were written out. E.g. Channel instead of Ch or Alternative instead of Alt. These abbreviations have no benefit in a time of auto-completion. Since Hopac already uses different names for the same concepts in CML (‘thread’ vs. ‘job’, ‘event’ vs. ‘alternative’), Hopac could give them descriptive names to help beginners understand their semantics and make CML-abstractions more popular.

This is how I would describe their semantics and name them (based on my limited understanding of their semantics so far, so they may be way off, but you get the idea):

• Job<'x>: placeholder for the eventual result of a deferred concurrent operation that will each be run concurrently in a time-slice of shared thread when the operation is started. The deferred concurrent operation may be started asynchronously without awaiting its result or it may be started synchronously to await its result. -> Deferred<'result>
• Alt<'x>: placeholder for the eventual result of a deferred concurrent operation that supports selective synchronous communication via non-deterministic choice
  -> Awaited<'result>
• Promise<'x>: placeholder for the eventual cached result of a deferred concurrent operation that is executed only once and that supports selective synchronous communication via non-deterministic choice -> AwaitedOnce<'result> (and rename the memo function to cache or memorize).
• Ch<'x>: unbuffered channel that represents an appointment to set up a ‘simple rendezvous’ (= a meeting at an agreed time and place) between two jobs so that one job can synchronously transfer a value to the other job, i.e. first job to give/take a value waits on the other job to take/give the value -> Passed<'value> or Transferred<'value>
• IVar<'x>: synchronizing emptied container of single value for single assignment by an exclusive owner -> AssignedOnce<'value>
• MVar<'x>: synchronizing emptied container of single value for multiple assignments by serialized owners (only one at a time) -> AssignedSerially<'value>

I think these new names differentiate the different semantics and describe their intended usage pretty well (assuming I do not misunderstand their semantics). You could created type synonyms for the old names to avoid breaking all code, but let new users benefit from the more descriptive names. Maybe also come up with an unambiguous name for run, e.g. start_and_await instead of run to make clear that this is a synchronous variant of start. start could be renamed to start_asynchronously to make clear that this is an asynchronous variant.

Disclaimer: I do not have any practical experience with Hopac (or any another implementation of CML) so far. I have not read the book on CML, but I am familiar with the related concepts in Go and Clojure's core.async. At this point I am just trying to roughly understand how Hopac is similar/different and what the API provides out-of-the box. My current (limited) understanding of Hopac is only based on reading Hopac's documentation including its guide, reading the descriptions of types in the reference in addition to reading @neoeinstein's excellent introduction and presentation.

[haf]

-1 for the renames @21c-HK suggests. I also disagree with the justification; there's no good auto-complete for huge F# projects in Ionide, so I type the Hopac functions and types all the time.

I think this project shouldn't focus on making it easier to understand, but making it easier to get started and find documentation and experimenting. Perhaps we can compile to wasm?

[voronoipotato]

Yes I agree with @haf. Nearly all the names @21c-HK proposed are more intimidating, longer, not actually any clearer. The only names that could possibly change are IVar and MVar. IVar presumably isn't an interface so that's a bit confusing. MutVal<'X> ImmVal<'X> might be a bit clearer while still being not any longer than Promise.

[wallymathieu]

Perhaps having AndThen when you want to use the library from say c#? bind seems quite prevalent in FSharp.Core and other libraries, so it might confuse people if you add another word for it.

[voronoipotato]

I think bind is fine. If you want to improve ease of use focus on exposing computation expressions in documentation. Most F# programmers are at least experienced in consuming CE's.