Removing the usage of X structures (or their names) in independent code

Removing the usage of X structures (or their names) in independent code

[Alex Gramiak]

Numerous internal procedures in Emacs that aren't tied to X expect and
use structures with the same name as X structures: e.g., XColor,
XGCValues, GC, XRectangle, XChar2b, Display, Pixmap, Cursor.

This poses an issue when attempting to use a non-X backend to Emacs that
conditionally uses X itself: name clashes occur between the structures
intended for use in the independent Emacs code and the internal X
structures. Workarounds using the preprocessor exist but are ugly and
fragile.

What would be the preferred way to fix this situation? Two options are
to use typedefs for these structures like XImagePtr_or_DC, or to use
unions. Everything else being equal, I would prefer the union approach.

Alternatively, for structures like XColor, there could be new generic
structures that all the backends share, but that would involve some
overhead on the X side for conversion.

Re: Removing the usage of X structures (or their names) in independent code

[Eli Zaretskii]

> From: Alex Gramiak <agrambot@gmail.com>
> Date: Wed, 08 May 2019 22:28:23 -0600
> 
> Numerous internal procedures in Emacs that aren't tied to X expect and
> use structures with the same name as X structures: e.g., XColor,
> XGCValues, GC, XRectangle, XChar2b, Display, Pixmap, Cursor.
> 
> This poses an issue when attempting to use a non-X backend to Emacs that
> conditionally uses X itself: name clashes occur between the structures
> intended for use in the independent Emacs code and the internal X
> structures. Workarounds using the preprocessor exist but are ugly and
> fragile.
> 
> What would be the preferred way to fix this situation? Two options are
> to use typedefs for these structures like XImagePtr_or_DC, or to use
> unions. Everything else being equal, I would prefer the union approach.

Why do you prefer a union?  It uglifies the code and makes it harder
to read and understand.  OTOH, having a backend-independent type (what
you call "typedef") is much cleaner.

> Alternatively, for structures like XColor, there could be new generic
> structures that all the backends share, but that would involve some
> overhead on the X side for conversion.

If that new structure is defined as (for example)

  typedef XColor EColor;

then there's no overhead at all: you could simply assign an EColor to
XColor or even use the former directly in APIs that want the latter.
For more complex situations, see what we do with 'struct font' and
'struct FOOfont' for font backend FOO.  So I'm not sure what overhead
did you have in mind.

Re: Removing the usage of X structures (or their names) in independent code

[Alex Gramiak]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Alex Gramiak <agrambot@gmail.com>
>> Date: Wed, 08 May 2019 22:28:23 -0600
>> 
>> Numerous internal procedures in Emacs that aren't tied to X expect and
>> use structures with the same name as X structures: e.g., XColor,
>> XGCValues, GC, XRectangle, XChar2b, Display, Pixmap, Cursor.
>> 
>> This poses an issue when attempting to use a non-X backend to Emacs that
>> conditionally uses X itself: name clashes occur between the structures
>> intended for use in the independent Emacs code and the internal X
>> structures. Workarounds using the preprocessor exist but are ugly and
>> fragile.
>> 
>> What would be the preferred way to fix this situation? Two options are
>> to use typedefs for these structures like XImagePtr_or_DC, or to use
>> unions. Everything else being equal, I would prefer the union approach.
>
> Why do you prefer a union?  It uglifies the code and makes it harder
> to read and understand.  OTOH, having a backend-independent type (what
> you call "typedef") is much cleaner.

The union approach would be more future-proof (if the goal of multiple
backends at once is realized), and I find it neater than having
different types per backend. I would consider the union approach as
having a "backend-independent type"; in the union approach, all backends
of Emacs would have that union as the type, whereas in the typedef
approach each backend pastes its own type into the generic parts of the
code.

The above goal is still far away, so it wouldn't be terrible to use
typedefs in the interim.

>> Alternatively, for structures like XColor, there could be new generic
>> structures that all the backends share, but that would involve some
>> overhead on the X side for conversion.
>
> If that new structure is defined as (for example)
>
>   typedef XColor EColor;
>
> then there's no overhead at all: you could simply assign an EColor to
> XColor or even use the former directly in APIs that want the latter.

Right, I meant overhead in the case of defining a new structure rather
than defining a new name for the structure. For example:

struct EColor
{
  uint16_t red;
  uint16_t blue;
  uint16_t green;
  uint16_t alpha; /* Who knows, maybe? */
  unsigned long long pixel;
};

Which would need to be converted to XColor on the X backend.

> For more complex situations, see what we do with 'struct font' and
> 'struct FOOfont' for font backend FOO.

Could you point me to somewhere specific for this? I'm unsure to what
you're referring.

In any case, would you prefer using names like EColor, EPixmap, EGC, or
Emacs_Color, Emacs_Pixmap, Emacs_GC?

Re: Removing the usage of X structures (or their names) in independent code

[Eli Zaretskii]

> From: Alex Gramiak <agrambot@gmail.com>
> Cc: emacs-devel@gnu.org
> Date: Thu, 09 May 2019 10:26:44 -0600
> 
> > Why do you prefer a union?  It uglifies the code and makes it harder
> > to read and understand.  OTOH, having a backend-independent type (what
> > you call "typedef") is much cleaner.
> 
> The union approach would be more future-proof (if the goal of multiple
> backends at once is realized), and I find it neater than having
> different types per backend. I would consider the union approach as
> having a "backend-independent type"; in the union approach, all backends
> of Emacs would have that union as the type, whereas in the typedef
> approach each backend pastes its own type into the generic parts of the
> code.
> 
> The above goal is still far away, so it wouldn't be terrible to use
> typedefs in the interim.

Yes, I'd prefer not to make changes that are needed by future far-away
goals, especially when those changes makes the code less readable.

> > If that new structure is defined as (for example)
> >
> >   typedef XColor EColor;
> >
> > then there's no overhead at all: you could simply assign an EColor to
> > XColor or even use the former directly in APIs that want the latter.
> 
> Right, I meant overhead in the case of defining a new structure rather
> than defining a new name for the structure. For example:
> 
> struct EColor
> {
>   uint16_t red;
>   uint16_t blue;
>   uint16_t green;
>   uint16_t alpha; /* Who knows, maybe? */
>   unsigned long long pixel;
> };
> 
> Which would need to be converted to XColor on the X backend.

But that's not needed if you use typedef as above for X.  And for
non-X platforms we already have a definition of XColor, which just
needs to be renamed to EColor.

> > For more complex situations, see what we do with 'struct font' and
> > 'struct FOOfont' for font backend FOO.
> 
> Could you point me to somewhere specific for this? I'm unsure to what
> you're referring.

For example, in ftfont.h:

struct font_info
{
  struct font font;
#ifdef HAVE_LIBOTF
  bool maybe_otf;	/* Flag to tell if this may be OTF or not.  */
  OTF *otf;
#endif	/* HAVE_LIBOTF */
  FT_Size ft_size;
  int index;
  [...]
}

And an example how this is used in xftfont.c:

static int
xftfont_draw (struct glyph_string *s, int from, int to, int x, int y,
              bool with_background)
{
  block_input ();

  struct frame *f = s->f;
  struct face *face = s->face;
  struct font_info *xftfont_info = (struct font_info *) s->font;

This is for when you need to extend a platform-independent struct (in
this case 'struct font') with platform-dependent additions.

> In any case, would you prefer using names like EColor, EPixmap, EGC, or
> Emacs_Color, Emacs_Pixmap, Emacs_GC?

The Emacs_ prefix is short enough, so I guess it's better.

Re: Removing the usage of X structures (or their names) in independent code

[Alex Gramiak]

Eli Zaretskii <eliz@gnu.org> writes:

> But that's not needed if you use typedef as above for X.  And for
> non-X platforms we already have a definition of XColor, which just
> needs to be renamed to EColor.

I meant if one were to use a non-XColor-like struct even in the X case, but
there's no reason for that now.

>> > For more complex situations, see what we do with 'struct font' and
>> > 'struct FOOfont' for font backend FOO.
>> 
>> Could you point me to somewhere specific for this? I'm unsure to what
>> you're referring.
>
> For example, in ftfont.h:
> [..]

Thanks, that's good to know for the future.


I posted a patch series to the scratch/X_Typedefs branch. WDYT?

The first few patches are straightforward, but the XChar2b patch is a
bit more involved.

Regarding the last patch, I don't like the names Emacs_Pix_Container
(XImagePtr) and Emacs_Pix_Context (XImagePtr_or_DC), but I'm lost as to
better names.

AFAIU XImage is a client-side structure holding bitmap/pixmap data[1].
My first thought was "Emacs_Pixmap_Container", but that would be easily
confused for a container for Emacs_Pixmap. At least the abbreviation
dissociates the two structures a bit.

[1] https://tronche.com/gui/x/xlib/graphics/images.html

Re: Removing the usage of X structures (or their names) in independent code

[Alex Gramiak]

Alex Gramiak <agrambot@gmail.com> writes:

> I posted a patch series to the scratch/X_Typedefs branch. WDYT?
>
> The first few patches are straightforward, but the XChar2b patch is a
> bit more involved.
>
> Regarding the last patch, I don't like the names Emacs_Pix_Container
> (XImagePtr) and Emacs_Pix_Context (XImagePtr_or_DC), but I'm lost as to
> better names.
>
> AFAIU XImage is a client-side structure holding bitmap/pixmap data[1].
> My first thought was "Emacs_Pixmap_Container", but that would be easily
> confused for a container for Emacs_Pixmap. At least the abbreviation
> dissociates the two structures a bit.
>
> [1] https://tronche.com/gui/x/xlib/graphics/images.html

Ping. Any comments? I'd like to merge this branch to master.

Re: Removing the usage of X structures (or their names) in independent code

[Eli Zaretskii]

> From: Alex Gramiak <agrambot@gmail.com>
> Cc: emacs-devel@gnu.org
> Date: Mon, 13 May 2019 10:15:53 -0600
> 
> Alex Gramiak <agrambot@gmail.com> writes:
> 
> > I posted a patch series to the scratch/X_Typedefs branch. WDYT?
> >
> > The first few patches are straightforward, but the XChar2b patch is a
> > bit more involved.
> >
> > Regarding the last patch, I don't like the names Emacs_Pix_Container
> > (XImagePtr) and Emacs_Pix_Context (XImagePtr_or_DC), but I'm lost as to
> > better names.
> >
> > AFAIU XImage is a client-side structure holding bitmap/pixmap data[1].
> > My first thought was "Emacs_Pixmap_Container", but that would be easily
> > confused for a container for Emacs_Pixmap. At least the abbreviation
> > dissociates the two structures a bit.
> >
> > [1] https://tronche.com/gui/x/xlib/graphics/images.html
> 
> Ping. Any comments? I'd like to merge this branch to master.

Sorry, I was busy and haven't yet time to review the patches.
Hopefully tomorrow.