Java thread safety and other server questions

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

Java thread safety and other server questions

James Moger
I'm playing around with integrating Asciidoctor into Gitblit, my pure java git server.

I don't know much about how JRuby operates and how Asciidoctor fires it up.  Is there any information or concerns about thread-safety?  Right now I'm calling Asciidoctor.create() for each render request.  Is that the recommended practice or should I be creating and reusing a singleton?

I also read through issue 101 (shutdown) and 102 (JBoss) so it seems that there are some changes coming that improve server-side usage - which are important to me.

I see there are some extension processor classes.  Could I tap into that to control document (html) generation?  Specifically, can I control the generation of relative links or image links?
Reply | Threaded
Open this post in threaded view
|

Re: Java thread safety and other server questions

LightGuardjp
Administrator
On Tue, Nov 12, 2013 at 7:42 PM, James Moger [via Asciidoctor :: Discussion] <[hidden email]> wrote:
I'm playing around with integrating Asciidoctor into Gitblit, my pure java git server.

Welcome to the list! Sorry for the delayed response, many of us were at Devoxx last week and still playing catch up.
 
I don't know much about how JRuby operates and how Asciidoctor fires it up.  Is there any information or concerns about thread-safety?  Right now I'm calling Asciidoctor.create() for each render request.  Is that the recommended practice or should I be creating and reusing a singleton?

Alex will certainly be able to answer this correctly, but due to #101 you'd probably be better off to use a singleton. Things should be thread safe. GitHub uses the core ruby (which AsciidoctorJ aka asciidoctor-java-integration uses as well), so I would doubt there would be thread safety issues.
 
I also read through issue 101 (shutdown) and 102 (JBoss) so it seems that there are some changes coming that improve server-side usage - which are important to me.

I see there are some extension processor classes.  Could I tap into that to control document (html) generation?  Specifically, can I control the generation of relative links or image links?

Yes, you should be able to do those sorts of things with an extension.

--
Reply | Threaded
Open this post in threaded view
|

Re: Java thread safety and other server questions

asotobu
Hi,

well in theory it should be thread-safe, because this module basically pass the calls from Java part to Ruby part, acts as a bridge, there is no state variables (only the asciidoctor interface to asciidoctor Ruby implementation).

But reading https://kenai.com/projects/jruby/pages/RedBridge you can see there are some way to make each variable thread aware. I am pretty sure that in our case it is not necessary do nothing special because in our case as I said there is only one asciidoctor instance which is an instance of Ruby asciidoctor class. In this case I think that we should know if Ruby Asciidoctor implementation can have any problem with multithreading.

Alex.
Reply | Threaded
Open this post in threaded view
|

Re: Java thread safety and other server questions

mojavelinux
Administrator

First, let me say, "Welcome!"

I'm super excited to hear you are exploring Asciidoctor for gitblit!

Ideally you want to use a singleton or pooled instance (probably best) because it eliminates the recurring startup cost and allows JRuby to start leveraging the JIT.

As Alex mentioned, state is confined to the document's AST, so the model naturally lends itself to a threaded environment.

However, thread safety is something you want to be absolutely sure about, so we should carefully review the scenarios before we commit to the statement that it's totally safe.

There is one open thread safety issue regarding how custom template are cached. (Only applicable if you have custom templates). We just need to switch the data structure to a concurrent map, which is provided by the gem referenced in the issue.

Custom extensions are okay if all setup is done inside a guard when the Asciidoctor instance is created. There's probably more we can do here to make that initialization atomic.

Finally, there are some controls we are planning to add that we'll have to take care don't violate thread safety. For instance, there are shared state compliance settings. We should only allow these to be modified during initialization and pass a compliance object to the document for subsequent changes.

To answer your question about customizing the HTML, I'll point you to the custom templates. These allow you to customize up to 100% of the HTML that Asciidoctor produces. You only have to override the templates you want to customize.

In your case, you'll want to modify:

- inline_image
- block_image
- inline_anchor

Copy the appropriate files from the asciidoctor-backends repository into a custom directory, tweak them, then specify the directory path in the options when you setup the Asciidoctor instance.

TIP: I prefer and recommend the slim template language as it's the most concise & readable.

There's also an extension API in Asciidoctor, but that's for when you want to extend the syntax or alter the  document structure. The render templates are what you want to use for customizing the HTML most of the time.

Btw, you should have a chat with the bintray development team. They are using AsciidoctorJ for almost the exact same use case as yours.

Cheers!

-Dan

On Nov 22, 2013 2:09 AM, "asotobu [via Asciidoctor :: Discussion]" <[hidden email]> wrote:
Hi,

well in theory it should be thread-safe, because this module basically pass the calls from Java part to Ruby part, acts as a bridge, there is no state variables (only the asciidoctor interface to asciidoctor Ruby implementation).

But reading https://kenai.com/projects/jruby/pages/RedBridge you can see there are some way to make each variable thread aware. I am pretty sure that in our case it is not necessary do nothing special because in our case as I said there is only one asciidoctor instance which is an instance of Ruby asciidoctor class. In this case I think that we should know if Ruby Asciidoctor implementation can have any problem with multithreading.

Alex.


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Java-thread-safety-and-other-server-questions-tp976p1051.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML