I find the Learn page particularly hard to navigate (Mozilla Firefox 91.13.0esr on Debian 11):
Thank you for including the browser version - this is quite different from what I see on all the browsers I have installed and clearly not what was intended here. Are there any nonstandard settings (e.g. font size) used?
Clearly, the intention of ocamlformat here is to link directly to the documentation. After we fix the URL structure to allow people to link to the latest version of the documentation of a package (Adding latest url to package links by SaySayo · Pull Request #793 · ocaml/ocaml.org · GitHub), the link on the GitHub repository’s README can be updated to go directly to the documentation.
It may be a better experience to disable Brave’s speed reader mode (https://twitter.com/brave/status/1559235636464418816) for these pages as it is not a high-priority problem compared to more pressing issues.
please don’t do that, it will have the same effect “they don’t know what they are talking about”. Memoization is a useful trick in general, Multicore is great technology, I’m just advising against choosing a too simple example, because for this particular example a much simpler and faster solution exist.
(every mathematician knows that a linear recurrence of order 2 can be transformed into a recurrence of order 1 (hence linear complexity) acting on pairs)
For instance here, just use let fib n = let rec loop n = if n < 1 then (0, 1) else let x, y = loop (n-1) in y, (x+y) in snd (loop n);;
Of course, the memoization is also O(n), but it’s like a big hammer when there is a much more elegant solution, and I’m sure ocamlers like fast and elegant solutions
For lightweight concurrent processes (those are provided separately in Domainslib though…), channel communication and message passing, atoms/symbols (well-typed thanks to polymorphic variants!), etc… I think something like erlang’s ping-pong would turn some heads.
The problem is 1. we will have to rely on domainslib, and 2. although I imagine we’re as performant, if not more, than erlang in terms of lightweight processes cost and runtime efficiency (perhaps not scheduling, their runtime is of course more battle-tested), our concurrency prims don’t look as nice currently. There’s more to write by hand than just:
I think this implementation makes sense though, fib (n-1) in this definition is roughly “half the work” of fib n.
This implementation of fib is the one doing the most work (of the usual definitions you see around), and also the one with the most visible slowdown, so using it expresses concisely (and elegantly IMO) the idea of “splitting a heavy workload on multiple CPUs”.
It would make way less sense it you were using it for just advertising the language of course, not multicore capabilities.
I’m not a specialist of parallel computing, but it seems to me that computation on large vectors (or matrices) is a predilection area. I just wrote a (probably too) simple implementation of a dot product, and on my laptop it’s already quite faster than the sequential loop:
let num_domains = 2
(** Sequential implementation of the dot product of the sub-arrays of
[a] and [b] of length [l] starting at index [i]. *)
let dot_seq a b i l =
let x = ref 0. in
for j = i to i+l-1 do
x := !x +. a.(j) *. b.(j)
done;
!x
(** Dot product of [a] and [b]. Parallel implementation, which simply
splits the array into [num_domains] subarrays, each of which is
computed sequentially by [dot_seq], and finally combines the
results to sum them. *)
let dot a b =
let n = Array.length a in
assert (n = Array.length b);
let l = n / num_domains in
let rec loop i d spawns =
if d = 0 then spawns
else let l = if d = 1 then n - i else l in
loop (i+l) (d-1)
((Domain.spawn (fun () -> dot_seq a b i l)) :: spawns) in
loop 0 num_domains []
|> List.map Domain.join
|> List.fold_left ( +. ) 0.
I’m assuming the OCaml playground is for beginners. If so, then it would be tremendously helpful if the OCaml playground example worked on beginners’ computers. For example, the Domainslib used in the example is not generally available for a beginner to use on Windows. Domainslib requires OCaml 5, and that is only available for mingw Windows, which is not something to ask beginners to install.
Someone can correct me if I’m wrong but there is no backport of Domainslib to 4.x (if that even made sense, which is doubtful).
From what I see in other languages and frameworks: Playgrounds serve these purposes:
(1) entice beginners to try out basic examples right in their browser so they do not have to install anything
(2) help people share smallish code snippets in forums/chats in such a way that someone else can help them debug, or
(3) as a way to quickly answer someone else’s question with some code snippet (which is confirmed to run because they used the playground to write it)
(4) for package authors to provide code examples that potential users of the package can tinker with (requires a playground that can import any packages).
Oh that makes sense. That is probably why the Rust playground is just a prototypical Hello World example.
Still, have you seen official code examples on a playground where it can’t be run on a large percentage of the viewers’ computers?
My two cents would be:
a one-liner program like let () = print_endline "Hello, world!";; by default
have a URL parameter for the playground like https://ocaml.org/play?template=parallel-domains-example that can be used in all the OCaml 5 (ex. “Try it now”) pages. Obviously that template URL parameter (or something similar) would control what was populated in the playground, and that is unplanned extra work.
the parallel-domains-example could come with a brief comment at the top (* You would need OCaml 5 for this example on a PC. That is available for many platforms at https://ocaml.org/news/ocaml-5.0, with more platforms coming soon. *).
For comparison, the ReScript playground has a tiny React component for their default. Cool thing about that is it shows a strength of ReScript, but is also simple. Now, I’m not sure what the analog of that in the OCaml world would be, but it may be cool to to try and think of some “killer feature” to show off. (Not sure which killer feature, but still worth thinking about.)
A dot product is memory-bound: 1 cold memory access per arithmetic operation. So, increasing the number of domains will not make it faster. Bytecode interpretation, however, is compute-bound. So, you will get a nice linear speedup, until either it becomes as fast as native code execution (and thus memory-bound) or you saturate the cores of your computer.
Keep in mind that, at each loop iteration, your code tests twice whether the array accesses are in bound and whether the domain needs to synchronize with the other domains to perform a garbage collection. Even if all these tests are perfectly predicted by the processor, their sheer amount still mess with the speculative execution, which means that your core does not run as fast as it theoretically could (e.g., what you would get with the same code written in C). So, the memory can keep up, and you still experience a small speedup by going from one domain to two domains.
I am pretty sure that, if you use four domains instead (assuming you have at least four cores), you will not see any additional speedup for native code, while you will still see a 2x speedup for bytecode.
By the way: In case someone who has time at their hands to contribute reads here:
You can always reach out to any of the maintainers on GitHub - ocaml/ocaml.org: The official OCaml website. with a feature/improvement that you want to contribute and we’ll be happy to guide you, pair program, and review speedily. For bigger contributions, do always approach us, because sometimes it is not obvious what exactly is already being worked on behind the scenes.
Not enjoying the content? Wanting to add an academic institution that uses OCaml to the list? Want to post an open OCaml position at your company? You can
(1) fork the GitHub repository, create a branch with your suggested changes and open a pull request, or
(2) open an issue on the GitHub repository, or
(3) send an email.
In contrast to publishing your own OCaml package, this is a much more casual way of contributing to the success of OCaml: maintenance is taken care of, you can focus solely on improving or adding features and content!
Here’s the promised update on what kind of feedback we got out of the user survey. I tried to distill as best as I could, there was so much feedback!
We have responses from 20 people in total, and a lot of those have volunteered to be interviewed by Claire. So this is excellent! In the interest of getting a good overview of the userbase, Claire will select people and send out invites.
Summary:
17 people are using OCaml for personal projects, 7 for business purposes, and 6 use OCaml for research purposes.
We have a good mix of junior and senior software development and research roles, as well as organisations of varying sizes and a broad mix of tasks people work on. I do not list these individually.
Problems with the rendering of documentation of modules included within another module (upstream odoc)
Problems with white space, font size, layout and color, and accessibility e.g. scaling up the page gives the mobile layout (please keep opening issues with screenshots, if applicable)
Documentation link on package overview page is hard to spot (changes have been applied, but layout changes are still pending to be discussed / sketched)
Lack of “jump to source code”-links (feature is upcoming, prototype exists, no release date yet)
Lack of proper dark mode (not a current priority, but we’re aware, possible contribution opportunity)
Tree view can get very busy for packages with lots of items
Ideas/suggestions package documentation:
Tree navigation should be improved, e.g. library vs toplevel module should be consolidated, hiding other libraries when going down into a module should be removed
Index for declarations (values, types, exceptions, etc.) of a module could be displayed in place of the empty TOC / appended to the TOC
Problems with content and documentation writing experience:
Lack of example code, quality of documentation on package docs displayed on ocaml.org
UI/UX of odoc for writing package documentation could be improved
hard to incorporate ocamldoc and markdown when writing documentation
Difficulty level/prerequisites of tutorials not always clear
Lack of important content (e.g. “single-page syntax introduction”, dune and opam guide, task-oriented examples for different levels of language learning)
Styling difference between manual/stdlib API and main pages
“Standard Library API” link goes to the index instead of to Chapter 28 of the OCaml manual (manual gives a more adequate introduction to the standard library for beginners and does not expose internal functions like the automatically generated index does)
Problems with outdated information
Pain points overall:
Site doesn’t motivate people enough to use OCaml by showing how OCaml is cool, interesting, nice to use and how using it makes you a better programmer
Ideas/suggestions learning section:
The more basic sections, e.g. if statements, pointers, could be merged or made collapsible to make it easier to see all items on the side navigation
“Papers” section is not so relevant to most OCaml beginners and should be moved below “Books”
Have a “beginner”/“advanced” toggle at the top of the learn page that switches the content area to be tailored better to the different use cases
add more context on who should read a particular book (e.g. prerequisites, topics covered)
Workarounds learning section:
directly go to the manual
books, blogs, other sites
ask on forum/discord/StackOverflow
check ocamlverse
Tbh, this took a bit longer than I thought: there is so much useful info in your feedback! I want to add links to corresponding issues, but this will have to wait until I edit this post tomorrow.
when odoc builds documentation, the “type” or “val” keywords are displayed strongly (boldface), whereas the information it provides, while being theoretically important, is of very little use in practice compared to the particular name of the value or of the type.
In fact, the name of the value/function/type should be much more prominent, in my opinion (this means also compared to the signature of the function). This is what most other languages docs do. I just made a comparison test for this:
compare: