+2.34.0:
+
+2012-10-21 Murray Cumming <murrayc@murrayc.com>
+
+ 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 <murrayc@murrayc.com>
+
+ 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 <kjell.ahlstedt@bredband.net>
-2.33.14 (unstable):
-
-
-2012-10-12 Kjell Ahlstedt <kjell.ahlstedt@bredband.net>
-
- 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 <jaalburquerque@gmail.com>
-
- 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:
## You should have received a copy of the GNU Lesser General Public License
## along with this library. If not, see <http://www.gnu.org/licenses/>.
-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])
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 <macro dir>])
_WRAP_METHOD(Glib::RefPtr<InterfaceInfo> lookup_interface(const Glib::ustring& name), g_dbus_node_info_lookup_interface, refreturn)
_WRAP_METHOD(Glib::RefPtr<const InterfaceInfo> 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<InterfaceInfo> lookup_interface();
- //TODO: Documentation:
+ /** Looks up information about the first interface.
+ */
Glib::RefPtr<const InterfaceInfo> lookup_interface() const;
//TODO: _WRAP_METHOD(void generate_xml(guint indent, GString* string_builder), g_dbus_node_info_generate_xml)
const Glib::RefPtr<Cancellable>& 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<Server>(new Server(address, guid, observer,
- //cancellable, flags));
-
- GError* gerror = 0;
-
- Glib::RefPtr<Server> result =
- Glib::wrap(g_dbus_server_new_sync(address.c_str(),
- static_cast<GDBusServerFlags>(flags),
- guid.c_str(),
- Glib::unwrap(observer),
- Glib::unwrap(cancellable),
- &gerror));
-
- if(gerror)
- ::Glib::Error::throw_exception(gerror);
-
- return result;
+ return Glib::RefPtr<Server>(new Server(address, guid, observer,
+ cancellable, flags));
}
Glib::RefPtr<Server> Server::create_sync(const std::string& address,
const Glib::RefPtr<Cancellable>& 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<Server>(new Server(address, guid,
- //cancellable, flags));
-
- GError* gerror = 0;
-
- Glib::RefPtr<Server> result =
- Glib::wrap(g_dbus_server_new_sync(address.c_str(),
- static_cast<GDBusServerFlags>(flags),
- guid.c_str(), 0,
- Glib::unwrap(cancellable),
- &gerror));
-
- if(gerror)
- ::Glib::Error::throw_exception(gerror);
-
- return result;
+ return Glib::RefPtr<Server>(new Server(address, guid,
+ cancellable, flags));
}
Glib::RefPtr<Server> Server::create_sync(const std::string& address,
const Glib::RefPtr<AuthObserver>& 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<Server>(new Server(address, guid, observer,
- //flags));
-
- GError* gerror = 0;
-
- Glib::RefPtr<Server> result =
- Glib::wrap(g_dbus_server_new_sync(address.c_str(),
- static_cast<GDBusServerFlags>(flags),
- guid.c_str(),
- Glib::unwrap(observer),
- 0,
- &gerror));
-
- if(gerror)
- ::Glib::Error::throw_exception(gerror);
-
- return result;
+ return Glib::RefPtr<Server>(new Server(address, guid, observer,
+ flags));
}
Glib::RefPtr<Server> 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<Server>(new Server(address, guid, flags));
-
- GError* gerror = 0;
-
- Glib::RefPtr<Server> result =
- Glib::wrap(g_dbus_server_new_sync(address.c_str(),
- static_cast<GDBusServerFlags>(flags),
- guid.c_str(), 0, 0, &gerror));
-
- if(gerror)
- ::Glib::Error::throw_exception(gerror);
-
- return result;
+ return Glib::RefPtr<Server>(new Server(address, guid, flags));
}
} // namespace DBus
_WRAP_METHOD(Glib::RefPtr<Glib::Bytes> read_bytes(gsize count, const Glib::RefPtr<Cancellable>& 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>& 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);
* @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>& cancellable, int io_priority = Glib::PRIORITY_DEFAULT);
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}
*/
namespace Gio
{
-/** TODO
+/** A menu item for use with Gio::Menu.
*
* @newin{2,32}
*/
// 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)
_WRAP_METHOD(gssize write_bytes(const Glib::RefPtr<const Glib::Bytes>& bytes, const Glib::RefPtr<Cancellable>& 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<const Glib::Bytes>& bytes, const SlotAsyncReady& slot, const Glib::RefPtr<Cancellable>& 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<const Glib::Bytes>& bytes, const SlotAsyncReady& slot, int io_priority = Glib::PRIORITY_DEFAULT);
* 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
*/
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:
*/
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: