[m-rev.] for review: add example of calling Mercury libraries from Java

[Julien Fischer]

On Fri, 5 Dec 2014, Paul Bone wrote:

> On Fri, Dec 05, 2014 at 08:07:54PM +1100, Julien Fischer wrote:
>> On Fri, 5 Dec 2014, Peter Wang wrote:
>>> On Fri, 5 Dec 2014 13:44:13 +1100 (AEDT), Julien Fischer <jfischer at opturion.com> wrote:
>>>> diff --git a/samples/java_interface/standalone_java/JavaMain.java b/samples/java_interface/standalone_java/JavaMain.java
>>>> new file mode 100644
>>>> index 0000000..814f917
>>>> --- /dev/null
>>>> +++ b/samples/java_interface/standalone_java/JavaMain.java
>>>> @@ -0,0 +1,53 @@
>>> ...
>>>> +
>>>> +        // When we have finished calling Mercury procedures then we need to
>>>> +        // invoke any finalisers specified using ':- finalise' declarations in
>>>> +        // the set of Mercury libraries we are using.
>>>> +        // The static method run_finalisers() in the JavaInternal class does
>>>> +        // this.  It will also perform any Mercury runtime finalisation that
>>>> +        // may be needed.
>>>> +        //
>>>> +        JavaInternal.run_finalisers();
>>>> +
>>>> +        // The Mercury exit status (as set by io.set_exit_status/1) may be read
>>>> +        // from the static field 'exit_status' in the JavaInternal class.
>>>> +        //
>>>> +        out.println("JavaMain: Mercury exit status = "
>>>> +            + JavaInternal.exit_status);
>>>
>>> No, I disagree with documenting something called JavaInternal.
>>> I suggest creating a new class with two methods to begin with:
>>>
>>>    public static void run_finalisers()
>>>    public static int get_exit_status()
>>
>> I agree.  There should be a single class that acts as the public
>> API for the Java version of the runtime.  I was thinking of naming
>> it either Runtime or MercuryRuntime.  Does anyone have a preference
>> (or an alternative suggestion)?
>>
>
> I think that MercuryRuntime is less ambigious.

Yes, especially since Java itself has the class java.lang.Runtime ;-)

> In a workspace on my machine I've fixed the issue with creating the thread
> pool.  However there are some assumptions inside MercuryThreadPool that I
> made and will take longer to fix.  It looks as if the simplest fix will be
> to require users to call something to close the thread pool when they're
> finished with it.  So I can make the new MercuryRuntime class have a method
> called finalise() that does both run_finalisers() and stops the thread pool
> (if it's been started).

Having just a single method called finalise that is responsible for all
Mercury finalisation would be analagous with what the C backend does.

> Rhe more complicated solution is to make the thread pool threads
> "daemon" threads, which is Java-speak meaning that the threads will
> exit of the main thread exits.  The problem with that is that it may
> differ from other Mercury backends.  I beleive that we want all
> backends to wait for thread.spawn tasks to finish before finishing
> themselves, and depending on the application some of these tasks may
> need to write and close files.

Above all what we want is for all the backends to behave consistently.
Do we actually document the current behaviour anywhere?

> I'm leaning towards the first solution, especially since there would be a
> run_finalisers() function anyway.  Does anyone see any problems with that?

We'll add the finalise method to the new MercuryRuntime class and you
can hook it into that.  You should probably shut down the thread pool
*after* the user-specified finalisation predicates have been called
anyway.

Cheers,
Julien.