[gst-devel] Header file restructuring needed

[Erik Walthinsen]

On Wed, 14 Feb 2001, David I. Lehn wrote:

> By 'private' headers do you mean private to gstreamer or private to that
> class?  If it's just private to each class then just put the stuff at
> the top of the .c file.  Kind of like what newer glib code is doing.
Good point.  I mean private within libgst.so.  Code in various files tends
to access "private" fields in other objects quite a bit, and this is done
via accessor macros (fast, yet allow changes to the struct later if
needed).  This means that for a given .c, it has to have included the
header for the object it's peeking into.

This isn't a problem for the .c files at all, they simply include the
headers they need and all is well.  The problem is in the headers
themselves.  Here's an example:

object1: gint field1;
         gint field2;
         object2 *parent;
object2: GList *children; (of object1 *)
         object1 *entry;

Now, this isn't a problem if you have the typedefs up front:

typedef struct _object1 object1;
typedef struct _object2 object2;

...since each object can use these forward references to define them by
name.  But in our current header structure, the typedefs for each object
live in the same file as the actual definition.  object2's use of object1
is easy, it just includes object1.h.  But object1 can't use the name of
object2 unless it includes object2.h  Suddenly you have a circular header
inclusion, and somewhere someone's not going to find the definition it
needs.

The solution is to put all the typedefs up front, one way or another.
Either this means having a single file that contains nothing but all the
typedefs (not such a bad solution), or splitting between the header that
has the typedef and the header that has the struct definition.  Then you
have:

object1.h: typedef object1;
_object1.h: #include <object2.h>
            struct object1;
object2.h: typedef object2;
_object2.h: #include <object1.h>
            struct object2;

Note that in order for object2 to have access to object1's internal
fields, object2.c will have to include _object1.h in addition to
object1.h.

Either solution works, with the latter giving the advantage of better data
hiding and such.  We can ensure that no application peeks inside the
private data structures.

Hrm, another way to achieve that safety is to simply wrap the private
parts of the header in #ifdef LIBGST_PRIVATE, defined in CFLAGS while
building libgst.so.  Then the public headers are visible to users to give
them an idea of what's going on, and they can even force things if they
really, really have to (get the gun...).

> These are too non-standard.  Would be nice to stick to .h for editor
> file type detection and so on.
Right, that's why I don't like them.

> You could try:
>  public: gstpad.h
>  private: _gstpad.h
> That's fairly clear and goes along with private data naming that many
> people use.
Not bad.  I use that method in libcodec, although a bit differently.

Although I tend to agree with Wim that gstpad_priv.h would work nicely.
It makes it clear what the distincion is (in libcodec that's not so clear,
but that's for a different reason anyway), and isn't too long.  Richard
makes some good points, though I don't think we'll have trouble with
_priviledged.h ;-)

      Erik Walthinsen <omega at temple-baptist.com> - System Administrator
        __
       /  \                GStreamer - The only way to stream!
      |    | M E G A        ***** http://gstreamer.net/ *****
      _\  /_