Improvements to the shortcuts preference dialog (#9174)

[lyx.git] / src / support / unicode.h

diff --git a/src/support/unicode.h b/src/support/unicode.h
index 6e83180c10692edcbe03fcba4af10fb7a6d6c407..aad4f8d408f697ca7a7c11ca78769331f34f4d72 100644 (file)
--- a/src/support/unicode.h
+++ b/src/support/unicode.h
@@ -21,6 +21,27 @@
 
 namespace lyx {
 
+/**
+ * Wrapper for iconv(3).
+ *
+ * According to the POSIX standard, all specified functions are thread-safe,
+ * with some exceptions. The iconv() function is not listed as an exception:
+ * http://pubs.opengroup.org/onlinepubs/9699919799/xrat/V4_xsh_chap02.html#tag_22_02_09_09
+ * http://man7.org/linux/man-pages/man7/pthreads.7.html
+ *
+ * Therefore, you can use as many instances of this class in parallel as you
+ * like. However, you need to ensure that each instance is only used by one
+ * thread at any given time. If this condition is not met you get nasty
+ * mixtures of different thread data as in bug 7240.
+ *
+ * From a performance point of view it is best to use one static instance
+ * per thread for each in/out encoding pair. This can e.g. be achieved by
+ * using helpers for thread-local storage such as QThreadStorage or
+ * boost::thread_specific_ptr. A single static instance protected by a mutex
+ * would work as well, and might be preferrable for exotic encoding pairs.
+ * Creating local IconvProcessor instances should be avoided because of the
+ * overhead in iconv_open().
+ */
 class IconvProcessor
 {
 public:
@@ -28,7 +49,7 @@ public:
        /// copy constructor needed because of pimpl_
        IconvProcessor(IconvProcessor const &);
        /// assignment operator needed because of pimpl_
-       void operator=(IconvProcessor const &);
+       IconvProcessor & operator=(IconvProcessor const &);
        /// destructor
        ~IconvProcessor();
 
@@ -47,10 +68,14 @@ private:
        /// \return true if the processor is ready to use.
        bool init();
        /// hide internals
-       struct Impl;
+       class Impl;
        Impl * pimpl_;
 };
 
+/// Get the global IconvProcessor instance of the current thread for
+/// utf8->ucs4 conversions
+IconvProcessor & utf8ToUcs4();
+
 // A single codepoint conversion for utf8_to_ucs4 does not make
 // sense, so that function is left out.
 
@@ -66,6 +91,10 @@ std::vector<char_type> utf16_to_ucs4(unsigned short const * s, size_t ls);
 
 std::vector<unsigned short> ucs4_to_utf16(char_type const * s, size_t ls);
 
+/// Get the global IconvProcessor instance of the current thread for
+/// ucs4->utf8 conversions
+IconvProcessor & ucs4ToUtf8();
+
 // ucs4_to_utf8
 
 std::vector<char> ucs4_to_utf8(char_type c);