From ad3e9c96c53fac4222eb46b064f5187f595e1d25 Mon Sep 17 00:00:00 2001 From: DongHun Kwak Date: Sun, 6 Sep 2020 23:39:17 -0700 Subject: [PATCH] Imported Upstream version 2.34.0 --- ChangeLog | 22 ++++++++++++ NEWS | 23 +++---------- configure.ac | 4 +-- gio/src/dbusintrospection.hg | 6 ++-- gio/src/dbusserver.ccg | 82 ++++---------------------------------------- gio/src/inputstream.hg | 55 ++++++++++++++++++++++++++--- gio/src/menu.hg | 9 ++++- gio/src/menuitem.hg | 8 +++-- gio/src/outputstream.hg | 66 ++++++++++++++++++++++++++++++++--- glib/src/threads.hg | 19 ++++++++-- 10 files changed, 183 insertions(+), 111 deletions(-) diff --git a/ChangeLog b/ChangeLog index 55e90e2..d69c671 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,25 @@ +2.34.0: + +2012-10-21 Murray Cumming + + Add some documentation. + + * gio/src/dbusintrospection.hg: + * gio/src/dbusserver.ccg: + * gio/src/inputstream.hg: + * gio/src/menu.hg: + * gio/src/menuitem.hg: + * gio/src/outputstream.hg: + * glib/src/threads.hg: Deal with some TODOS, mostly + adding documentation based on the C documentation. + +2012-10-21 Murray Cumming + + Create only .tar.xz tarballs. + + * configure.ac: This is what ftp.gnome.org wants, so this avoids + it doing any repackaging. + 2.33.14: 2012-10-12 Kjell Ahlstedt diff --git a/NEWS b/NEWS index 26d070c..afa33c5 100644 --- a/NEWS +++ b/NEWS @@ -1,23 +1,8 @@ -2.33.14 (unstable): - - -2012-10-12 Kjell Ahlstedt - - gmmproc: Add 3-argument @newin. - - * tools/pm/DocsParser.pm: Convert "Since: 1.2.3" to "@newin{1,2,3}". - Some C projects (goocanvas, grilo, gstreamer) use "Since: 1.2.3", instead of - "Since: 1.2". The corresponding C++ projects need an ALIAS for this @newin - in Doxyfile.in, like in mm-common/skeletonmm/doc/reference/Doxyfile.in. - -2012-10-08 José Alburquerque - - FileInfo: set_attribute_strings(): Const correction. - - * gio/src/fileinfo.hg: Pass the attr_value vector as a const - std::vector<>& and not just a std::vecto<>&. I must not have been - paying attention to what I was doing when wrapping this. +2.34.0 (stable): +* Some minor documentation improvements. + (Murray Cumming) + 2.33.14: Glib: diff --git a/configure.ac b/configure.ac index 23e9b1f..1e3545b 100644 --- a/configure.ac +++ b/configure.ac @@ -15,7 +15,7 @@ ## You should have received a copy of the GNU Lesser General Public License ## along with this library. If not, see . -AC_INIT([glibmm], [2.33.14], +AC_INIT([glibmm], [2.34.0], [http://bugzilla.gnome.org/enter_bug.cgi?product=glibmm], [glibmm], [http://www.gtkmm.org/]) AC_PREREQ([2.59]) @@ -25,7 +25,7 @@ AC_CONFIG_AUX_DIR([build]) AC_CONFIG_MACRO_DIR([build]) AC_CONFIG_HEADERS([config.h glib/glibmmconfig.h gio/giommconfig.h]) -AM_INIT_AUTOMAKE([1.9 -Wno-portability dist-bzip2 no-define nostdinc tar-ustar]) +AM_INIT_AUTOMAKE([1.9 -Wno-portability no-dist-gzip dist-xz tar-ustar no-define nostdinc]) m4_ifdef([AM_SILENT_RULES], [AM_SILENT_RULES]) AM_MAINTAINER_MODE AC_ARG_VAR([ACLOCAL_FLAGS], [aclocal flags, e.g. -I ]) diff --git a/gio/src/dbusintrospection.hg b/gio/src/dbusintrospection.hg index 729b25d..1e15637 100644 --- a/gio/src/dbusintrospection.hg +++ b/gio/src/dbusintrospection.hg @@ -141,10 +141,12 @@ public: _WRAP_METHOD(Glib::RefPtr lookup_interface(const Glib::ustring& name), g_dbus_node_info_lookup_interface, refreturn) _WRAP_METHOD(Glib::RefPtr lookup_interface(const Glib::ustring& name) const, g_dbus_node_info_lookup_interface, constversion, refreturn) - //TODO: Documentation: + /** Looks up information about the first interface. + */ Glib::RefPtr lookup_interface(); - //TODO: Documentation: + /** Looks up information about the first interface. + */ Glib::RefPtr lookup_interface() const; //TODO: _WRAP_METHOD(void generate_xml(guint indent, GString* string_builder), g_dbus_node_info_generate_xml) diff --git a/gio/src/dbusserver.ccg b/gio/src/dbusserver.ccg index 9454bf2..8e22657 100644 --- a/gio/src/dbusserver.ccg +++ b/gio/src/dbusserver.ccg @@ -87,26 +87,8 @@ Glib::RefPtr Server::create_sync(const std::string& address, const Glib::RefPtr& cancellable, ServerFlags flags) { - //TODO: Use the constructor instead of the code underneath when - //g_dbus_server_new_sync() does not do more than call g_initable_new(). - //https://bugzilla.gnome.org/show_bug.cgi?id=639478 - //return Glib::RefPtr(new Server(address, guid, observer, - //cancellable, flags)); - - GError* gerror = 0; - - Glib::RefPtr result = - Glib::wrap(g_dbus_server_new_sync(address.c_str(), - static_cast(flags), - guid.c_str(), - Glib::unwrap(observer), - Glib::unwrap(cancellable), - &gerror)); - - if(gerror) - ::Glib::Error::throw_exception(gerror); - - return result; + return Glib::RefPtr(new Server(address, guid, observer, + cancellable, flags)); } Glib::RefPtr Server::create_sync(const std::string& address, @@ -114,25 +96,8 @@ Glib::RefPtr Server::create_sync(const std::string& address, const Glib::RefPtr& cancellable, ServerFlags flags) { - //TODO: Use the constructor instead of the code underneath when - //g_dbus_server_new_sync() does not do more than call g_initable_new(). - //https://bugzilla.gnome.org/show_bug.cgi?id=639478 - //return Glib::RefPtr(new Server(address, guid, - //cancellable, flags)); - - GError* gerror = 0; - - Glib::RefPtr result = - Glib::wrap(g_dbus_server_new_sync(address.c_str(), - static_cast(flags), - guid.c_str(), 0, - Glib::unwrap(cancellable), - &gerror)); - - if(gerror) - ::Glib::Error::throw_exception(gerror); - - return result; + return Glib::RefPtr(new Server(address, guid, + cancellable, flags)); } Glib::RefPtr Server::create_sync(const std::string& address, @@ -140,48 +105,15 @@ Glib::RefPtr Server::create_sync(const std::string& address, const Glib::RefPtr& observer, ServerFlags flags) { - //TODO: Use the constructor instead of the code underneath when - //g_dbus_server_new_sync() does not do more than call g_initable_new(). - //https://bugzilla.gnome.org/show_bug.cgi?id=639478 - //return Glib::RefPtr(new Server(address, guid, observer, - //flags)); - - GError* gerror = 0; - - Glib::RefPtr result = - Glib::wrap(g_dbus_server_new_sync(address.c_str(), - static_cast(flags), - guid.c_str(), - Glib::unwrap(observer), - 0, - &gerror)); - - if(gerror) - ::Glib::Error::throw_exception(gerror); - - return result; + return Glib::RefPtr(new Server(address, guid, observer, + flags)); } Glib::RefPtr Server::create_sync(const std::string& address, const std::string& guid, ServerFlags flags) { - //TODO: Use the constructor instead of the code underneath when - //g_dbus_server_new_sync() does not do more than call g_initable_new(). - //https://bugzilla.gnome.org/show_bug.cgi?id=639478 - //return Glib::RefPtr(new Server(address, guid, flags)); - - GError* gerror = 0; - - Glib::RefPtr result = - Glib::wrap(g_dbus_server_new_sync(address.c_str(), - static_cast(flags), - guid.c_str(), 0, 0, &gerror)); - - if(gerror) - ::Glib::Error::throw_exception(gerror); - - return result; + return Glib::RefPtr(new Server(address, guid, flags)); } } // namespace DBus diff --git a/gio/src/inputstream.hg b/gio/src/inputstream.hg index acfb9d3..ba55fa2 100644 --- a/gio/src/inputstream.hg +++ b/gio/src/inputstream.hg @@ -64,13 +64,60 @@ public: _WRAP_METHOD(Glib::RefPtr read_bytes(gsize count, const Glib::RefPtr& cancellable), g_input_stream_read_bytes, errthrow) - //TODO: Documentation. - /** + //TODO: Why not use _WRAP_METHOD() for this? + /** Request an asynchronous read of @a count bytes from the stream into a + * new Glib::Bytes. When the operation is finished @a slot will be called. + * You can then call read_bytes_finish() to get the result of the + * operation. + * + * During an async request no other sync and async calls are allowed, and will + * result in Gio::Error with PENDING being thrown. + * + * A value of @a count larger than MAXSSIZE will cause a Gio::Error with INVALID_ARGUMENT to be thrown. + * + * On success, the new Glib::Bytes will be passed to the callback. It is + * not an error if this is smaller than the requested size, as it can + * happen e.g. near the end of a file, but generally we try to read as + * many bytes as requested. Zero is returned on end of file (or if + * @a count is zero), but never otherwise. + * + * Any outstanding I/O request with higher priority (lower numerical + * value) will be executed before an outstanding request with lower + * priority. The default priority is PRIORITY_DEFAULT. + * + * @param count The number of bytes that will be read from the stream. + * @param slot Callback to call when the request is satisfied. + * @param cancellable A Cancellable object. + * @param io_priority The I/O priority of the request. + * * @newin{2,34} */ void read_bytes_async(gsize count, const SlotAsyncReady& slot, const Glib::RefPtr& cancellable, int io_priority = Glib::PRIORITY_DEFAULT); - /** + /** Request an asynchronous read of @a count bytes from the stream into a + * new Glib::Bytes. When the operation is finished @a slot will be called. + * You can then call read_bytes_finish() to get the result of the + * operation. + * + * During an async request no other sync and async calls are allowed, and will + * result in Gio::Error with PENDING being thrown. + * + * A value of @a count larger than MAXSSIZE will cause a Gio::Error with INVALID_ARGUMENT to be thrown. + * + * On success, the new Glib::Bytes will be passed to the callback. It is + * not an error if this is smaller than the requested size, as it can + * happen e.g. near the end of a file, but generally we try to read as + * many bytes as requested. Zero is returned on end of file (or if + * @a count is zero), but never otherwise. + * + * Any outstanding I/O request with higher priority (lower numerical + * value) will be executed before an outstanding request with lower + * priority. The default priority is PRIORITY_DEFAULT. + * + * @param count The number of bytes that will be read from the stream. + * @param slot Callback to call when the request is satisfied.h + * @param io_priority The I/O priority of the request. + * * @newin{2,34} */ void read_bytes_async(gsize count, const SlotAsyncReady& slot, int io_priority = Glib::PRIORITY_DEFAULT); @@ -117,7 +164,7 @@ public: * @param count The number of bytes that will be read from the stream. * @param slot Callback to call when the request is satisfied. * @param cancellable A Cancellable object. - * @param io_priority The I/O priority of the request. + * @param io_priority The I/O priority of the request. */ void read_async(void* buffer, gsize count, const SlotAsyncReady& slot, const Glib::RefPtr& cancellable, int io_priority = Glib::PRIORITY_DEFAULT); diff --git a/gio/src/menu.hg b/gio/src/menu.hg index 0f52734..d6e05e4 100644 --- a/gio/src/menu.hg +++ b/gio/src/menu.hg @@ -24,7 +24,14 @@ _PINCLUDE(giomm/private/menumodel_p.h) namespace Gio { -/** TODO +/** A simple implementation of GMenuModel. + * You populate a Menu by adding MenuItem instances to it. + * + * There are some convenience methods to allow you to directly + * add items (avoiding MenuItem) for the common cases. To add + * a regular item, use insert(). To add a section, use + * insert_section(). To add a submenu, use + * insert_submenu(). * * @newin{2,32} */ diff --git a/gio/src/menuitem.hg b/gio/src/menuitem.hg index 04bf068..51e5e84 100644 --- a/gio/src/menuitem.hg +++ b/gio/src/menuitem.hg @@ -24,7 +24,7 @@ _PINCLUDE(glibmm/private/object_p.h) namespace Gio { -/** TODO +/** A menu item for use with Gio::Menu. * * @newin{2,32} */ @@ -64,9 +64,13 @@ public: // Ignore varargs function. _IGNORE(g_menu_item_get_attribute) - //TODO: Documentation: + //TODO: Rename this to unset_action_target() and deprecate this one. + /** Unsets the target for the specified @a action. + */ void set_action_and_target(const Glib::ustring& action); + //TODO: Add unset_action_and_target(). + _WRAP_METHOD(void set_action_and_target(const Glib::ustring& action, const Glib::VariantBase& target_value), g_menu_item_set_action_and_target_value) _IGNORE(g_menu_item_set_action_and_target) _WRAP_METHOD(void set_detailed_action(const Glib::ustring& detailed_action), g_menu_item_set_detailed_action) diff --git a/gio/src/outputstream.hg b/gio/src/outputstream.hg index bcda7c9..fbfc6f1 100644 --- a/gio/src/outputstream.hg +++ b/gio/src/outputstream.hg @@ -128,13 +128,71 @@ public: _WRAP_METHOD(gssize write_bytes(const Glib::RefPtr& bytes, const Glib::RefPtr& cancellable{?}), g_output_stream_write_bytes, errthrow) - //TODO: Documentation. - /** + /** Request an asynchronous write of the data in @a bytes to the stream. + * When the operation is finished @a slot will be called. You can + * then call write_bytes_finish() to get the result of + * the operation. + * + * During an async request no other sync and async calls are allowed, + * and will result in Gio::Error with PENDING being thrown. + * + * A Glib:Bytes larger than MAXSSIZE will cause a Gio::Error with + * INVALID_ARGUMENT to be thrown. + * + * On success, the number of bytes written will be passed to the + * callback @a slot. It is not an error if this is not the same as the + * requested size, as it can happen e.g. on a partial I/O error, + * but generally we try to write as many bytes as requested. + * + * You are guaranteed that this method will never fail with + * IO_ERROR_WOULD_BLOCK - if the stream can't accept more data, the + * method will just wait until this changes. + * + * Any outstanding I/O request with higher priority (lower numerical + * value) will be executed before an outstanding request with lower + * priority. Default priority is Glib::PRIORITY_DEFAULT. + * + * For the synchronous, blocking version of this function, see write_bytes(). + * + * @param bytes The bytes to + * @param slot Callback slot to call when the request is satisfied. + * @param cancellable Cancellable object. + * @param io_priority The io priority of the request. + * * @newin{2,34} */ void write_bytes_async(const Glib::RefPtr& bytes, const SlotAsyncReady& slot, const Glib::RefPtr& cancellable, int io_priority = Glib::PRIORITY_DEFAULT); - /** + /** Request an asynchronous write of the data in @a bytes to the stream. + * When the operation is finished @a slot will be called. You can + * then call write_bytes_finish() to get the result of + * the operation. + * + * During an async request no other sync and async calls are allowed, + * and will result in Gio::Error with PENDING being thrown. + * + * A Glib:Bytes larger than MAXSSIZE will cause a Gio::Error with + * INVALID_ARGUMENT to be thrown. + * + * On success, the number of bytes written will be passed to the + * callback @a slot. It is not an error if this is not the same as the + * requested size, as it can happen e.g. on a partial I/O error, + * but generally we try to write as many bytes as requested. + * + * You are guaranteed that this method will never fail with + * IO_ERROR_WOULD_BLOCK - if the stream can't accept more data, the + * method will just wait until this changes. + * + * Any outstanding I/O request with higher priority (lower numerical + * value) will be executed before an outstanding request with lower + * priority. Default priority is Glib::PRIORITY_DEFAULT. + * + * For the synchronous, blocking version of this function, see write_bytes(). + * + * @param bytes The bytes to + * @param slot Callback slot to call when the request is satisfied. + * @param io_priority The io priority of the request. + * * @newin{2,34} */ void write_bytes_async(const Glib::RefPtr& bytes, const SlotAsyncReady& slot, int io_priority = Glib::PRIORITY_DEFAULT); @@ -179,7 +237,7 @@ public: * and will result in Gio::Error with PENDING being thrown. * * A value of @a count larger than MAXSSIZE will cause a Gio::Error with - * NVALID_ARGUMENT to be thrown. + * INVALID_ARGUMENT to be thrown. * * On success, the number of bytes written will be passed to the * callback @a slot. It is not an error if this is not the same as the diff --git a/glib/src/threads.hg b/glib/src/threads.hg index 89b8131..10ef5dd 100644 --- a/glib/src/threads.hg +++ b/glib/src/threads.hg @@ -234,7 +234,12 @@ private: */ Mutex* wrap(GMutex* gobject); -//TODO: Documentation +/** This represents a recursive mutex. + * It is similar to a Mutex with the difference + * that it is possible to lock a RecMutex multiple times in the same + * thread without deadlock. When doing so, care has to be taken to + * unlock the recursive mutex as often as it has been locked. + */ class RecMutex { public: @@ -296,7 +301,17 @@ private: */ RecMutex* wrap(GRecMutex* gobject); -//TODO: Documentation +/** This represents a reader-writer lock. + * It is similar to a Mutex in that it allows + * multiple threads to coordinate access to a shared resource. + * + * The difference to a mutex is that a reader-writer lock discriminates + * between read-only ('reader') and full ('writer') access. While only + * one thread at a time is allowed write access (by holding the 'writer' + * lock via writer_lock()), multiple threads can gain + * simultaneous read-only access (by holding the 'reader' lock via + * reader_lock()). + */ class RWLock { public: -- 2.7.4