From 7a3655a43ba9802b9dd653852aa0048804d786cf Mon Sep 17 00:00:00 2001 From: Yorick Peterse Date: Thu, 11 Sep 2014 23:39:10 +0200 Subject: [PATCH] Updated README intro + thread-safety section. --- README.md | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 63f4217..a49fb0e 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,14 @@ # Oga -Oga is an XML/HTML parser written in Ruby. Oga aims to provide an easy to use -and high performance API for all your XML/HTML parsing needs. Oga requires -nothing other than Ruby, it does not depend on libxml or other system libraries. +Oga is an XML/HTML parser written in Ruby. It provides an easy to use API for +parsing, modifying and querying documents (using XPath expressions). Oga does +not require system libraries such as libxml, making it easier and faster to +install on various platforms. To achieve better performance Oga uses a small, +native extension (C for MRI/Rubinius, Java for JRuby). -Oga uses a small native extension (C for MRI/Rubinius, Java for JRuby) to -speed up the process of lexing XML into tokens. Initial prototypes used a pure -Ruby setup but this proved to be too slow when consuming large input sizes. +Oga provides an API that allows you to safely parse and query documents in a +multi-threaded environment, without having to worry about your applications +blowing up. From [Wikipedia][oga-wikipedia]: @@ -86,6 +88,16 @@ gcc or clang. Oga's C extension can be compiled with both. JRuby does not require a compiler as the native extension is compiled during the Gem building process and bundled inside the Gem itself. +## Thread Safety + +Documents parsed using Oga are thread-safe as long as they are not modified by +multiple threads at the same time. Querying documents using XPath can be done by +multiple threads just fine. Write operations, such as removing attributes, are +_not_ thread-safe and should not be done by multiple threads at once. + +It is advised that you do not share parsed documents between threads unless you +_really_ have to. + ## Documentation The documentation is best viewed [on the documentation website][doc-website].