reference counting and memory management

[Jeevhi]

Is there any documentation on memory management. Two things specifically comes to mind:

• when to unref objects. In some of the example, unref is used but the documentation does not mention anything. Is there any guidelines on when to unref and when not to?

• Also, for the functions returning const char *, who should free them?

[jstedfast]

Functions that return const char * return a pointer to a string stored on the object that will be free'd when the object itself is free'd.

For unref, if the function that returned the object created the object, then you need to unref it, otherwise you don't.

For example:

GMimeStream *stream = g_mime_stream_mem_new ();

This object will need to be unref'd because we just allocated it.

GMimeStream *stream = g_mime_data_wrapper_get_stream (wrapper);

This function returns a reference to an existing GMimeStream object stored on the GMimeDataWrapper, so you do not unref this.

Where I suspect you might be confused is when you allocate a new object and then add it to another object.

For example:

GMimeStream *stream = g_mime_stream_mem_new ();
GMimeDataWrapper *wrapper = g_mime_data_wrapper_new_with_stream (stream, GMIME_CONTENT_ENCODING_DEFAULT);
g_object_unref (stream);

Even in this situation, it is necessary to unref the allocated object because all GMime functions that add an object to another object will ref that object themselves.

In other words, in the above example, the GMimeStream is being added to the GMimeDataWrapper. The GMimeDataWrapper ref's the stream which means that the stream object now has a ref count of 2. When you unref the stream after adding it to the data wrapper, the ref count reduces to 1. And when you eventually unref the data wrapper, the ref coun t will reduce to 0 thereby freeing the stream object.

[Jeevhi]

thanks, this was useful! possibly you can add it to documentation somewhere.

[jstedfast]

I've added a Memory Management section to the README with the above info.

Thanks.