Add example for parallel sort

[Connor-GH]

It is now clearer how to use this library. The example(s) are built by default.

[hkaiser]

@Connor-GH thanks for looking into this. @SAtacker would you mind haveing a look?

[pingu-73]

@SAtacker @hkaiser do we need to explicitly add examples 'coz it's pretty clear from tests how to use this library they simply work as examples.

[pingu-73]

@Connor-GH are you building hpx-rs on linux or mac ?

[Connor-GH]

I build it on linux.

[pingu-73]

I build it on linux.

could you please add instructions to build it on linux in the Readme.
Thanks

[Connor-GH]

@SAtacker @hkaiser do we need to explicitly add examples 'coz it's pretty clear from tests how to use this library they simply work as examples.

HPX has its tests, and it has its examples. Tests are meant to be entirely functional. People aren't really supposed to look at them until a regression pops up. On the other hand, HPX's examples are fairly small (can fit on one screen) and have some important comments. The examples are there for people who just need to quickly pick something up with the library and need to learn by doing, rather than searching for a specific flag or something (which is what the documentation is for).

This is probably best demonstrated visibly. Here is a simple example from HPX that I learned from to help develop this example (notice the comments):

• https://github.com/STEllAR-GROUP/hpx/blob/master/examples/throttle/spin.cpp
  If I were learning purely from tests, I would have to learn from code like this (notice the lack of comments):
• https://github.com/STEllAR-GROUP/hpx/blob/master/tests/regressions/block_matrix/algorithms.cpp

It should also be noted that examples should be separated from the implementation, but I don't think this matters wrt the testcases. Many languages have built-in unit tests, and I think putting them in the implementation file is fine. D does this for example in its standard library, but their tests are a bit more trivial but express the power of the API. There is a way of writing tests that can work as examples, and D does this this well, but these tests just serve to "get the thing done" with low regard for the potential of it being used to educate.

Maybe I am bikeshedding here, but there is a genuine case for both examples and tests.

[pingu-73]

@SAtacker @hkaiser do we need to explicitly add examples 'coz it's pretty clear from tests how to use this library they simply work as examples.

HPX has its tests, and it has its examples. Tests are meant to be entirely functional. People aren't really supposed to look at them until a regression pops up. On the other hand, HPX's examples are fairly small (can fit on one screen) and have some important comments. The examples are there for people who just need to quickly pick something up with the library and need to learn by doing, rather than searching for a specific flag or something (which is what the documentation is for).

This is probably best demonstrated visibly. Here is a simple example from HPX that I learned from to help develop this example (notice the comments):

• https://github.com/STEllAR-GROUP/hpx/blob/master/examples/throttle/spin.cpp
  If I were learning purely from tests, I would have to learn from code like this (notice the lack of comments):
• https://github.com/STEllAR-GROUP/hpx/blob/master/tests/regressions/block_matrix/algorithms.cpp

Maybe I am bikeshedding here, but there is a genuine case for both examples and tests.

i agree that examples are essential, but i don't think it's ideal to write one-liner examples as they don't add much value beyond what's already covered in the tests. It would be more beneficial to create more complex and practical examples. Since most of the functions maintain a similar structure and usage style as HPX it's ideal to refer to hpx documentation for understanding about that function (till the time we aren't done with hpx-rs documentation), more elaborate examples would help demonstrate their effective use.

@SAtacker what are your thoughts on it?

[SAtacker]

@SAtacker @hkaiser do we need to explicitly add examples 'coz it's pretty clear from tests how to use this library they simply work as examples.

HPX has its tests, and it has its examples. Tests are meant to be entirely functional. People aren't really supposed to look at them until a regression pops up. On the other hand, HPX's examples are fairly small (can fit on one screen) and have some important comments. The examples are there for people who just need to quickly pick something up with the library and need to learn by doing, rather than searching for a specific flag or something (which is what the documentation is for).
This is probably best demonstrated visibly. Here is a simple example from HPX that I learned from to help develop this example (notice the comments):

• https://github.com/STEllAR-GROUP/hpx/blob/master/examples/throttle/spin.cpp
  If I were learning purely from tests, I would have to learn from code like this (notice the lack of comments):
• https://github.com/STEllAR-GROUP/hpx/blob/master/tests/regressions/block_matrix/algorithms.cpp

Maybe I am bikeshedding here, but there is a genuine case for both examples and tests.

i agree that examples are essential, but i don't think it's ideal to write one-liner examples as they don't add much value beyond what's already covered in the tests. It would be more beneficial to create more complex and practical examples. Since most of the functions maintain a similar structure and usage style as HPX it's ideal to refer to hpx documentation for understanding about that function (till the time we aren't done with hpx-rs documentation), more elaborate examples would help demonstrate their effective use.

@SAtacker what are your thoughts on it?

I agree that trivial, one-liner examples may not add much value at this stage, as they are largely covered by the existing tests.
It would be more beneficial to focus on more complex and practical examples that showcase real-world use cases, especially considering that most of the functions in hpx-rs follow similar patterns and usage as in HPX.
For now, referring to HPX documentation for detailed function usage (until the HPX-RS documentation is ready) makes sense.
That said, since there’s already an example in this PR, I have no objections to including it for now.

[Connor-GH]

I apologize, I have been busy lately. I finally have a commit ready again for review though. By the time this PR is done, there should be no code that directly calls the ffi. IOW: all code needs to go through the "front door" of hpx_sys::, rather than hpx_sys::ffi::.

Things I don't like about this code that I am asking guidance on:

• I would really prefer not to pass this function pointer through by another static variable, but it was the only way I could find to keep the API of fn(Vec) to the user. It feels really bad, please work with me on fixing this.
• A bit too much unsafe code in the string conversion process and whatnot. Is there a safe way to go from Vec to *mut *mut c_char? It seems like there would be.

[Connor-GH]

How would we feel about this implementation?

https://github.com/Actyx/Actyx/blob/1f4bd6699a9345bde630248294b10bbc902d7230/rust/actyx/node-ffi/src/lib.rs#L70-L143

[SAtacker]

How would we feel about this implementation?

https://github.com/Actyx/Actyx/blob/1f4bd6699a9345bde630248294b10bbc902d7230/rust/actyx/node-ffi/src/lib.rs#L70-L143

I lost the context, could you please remind?

[pingu-73]

@SAtacker LGTM