TIP 695: Use enums and inline functions in C API

Login
EuroTcl/OpenACS 11 - 12 JULY 2024, VIENNA
Author:         Donal Fellows <[email protected]>
State:          Draft
Type:           Project
Vote:           Pending
Created:        10-Ma7-2024
Tcl-Version:    9.0

Abstract

This TIP proposes that our public header files use enums for most constants and inline functions for most "macros", where this makes reasonable sense. Note that it will not work for everything, but it should work for a lot.

Background

The Tcl and Tk headers use #defines quite extensively, and for various purposes. However, the use of such can cause a fair bit of re-parsing of the same thing over and over (reducing the speed of compilation) and may invite redefinition of things that we definitely won't ever support that for.

Specification

We have many #defines that are bits of flag fields or that are selecting a value from a small fixed series. These are ideal cases for an enum. We should define relevant enumeration types around them. Note that not all numeric values are suitable for this; for example, buffer sizes are better not converted this way as they're often overridable.

Similarly, many other #defines are effectively just little functions. If they're well-formed enough (not all are) then we should use a static inline function with the same name; such functions are not retained within the compilation unit by most compilers (with no warning generated on non-use), and result in efficient code use; the inline function is parsed once, not at every use in the compilation unit (a profound benefit in some parts of the bytecode compiler).

In both cases, there are some #defines that will unavoidably not be convertable. An example of these are the defines TCL_ALPHA_RELEASE (because it is used by non-C and non-C++ contexts), ckfree (because it needs to be type-flexible in its parameter on some platforms) and Tcl_DecrRefCount (because it acts as a stand-in for variants with extra context parameters in some builds). This last case is substantially more common in our internal headers.

As long as people use the symbol names as they've always been intended to be used, they should observe no differences due to this TIP.

Copyright

This document has been placed in the public domain.