6b18fc252d
We have g_idle_add() and g_timeout_add(). But these return
those odd guint source ids. That is totally pointless. The
only potential benefit is that a guint is only 4 bytes while
a pointer is 8 bytes (on 64 bit systems). Otherwise, it seems
always preferable to have an actual GSource instance instead
of an integer. It also saves the overhead in g_source_remove()
which first needs to do a hash lookup to find the GSource.
A GSource instance would theoretically work with multiple
GMainContext instances, while g_source_remove() only works
wit g_main_context_default().
On the other hand we have helper API like nm_g_idle_source_new()
and nm_g_timeout_source_new(), which is fully flexible and sensible
because it returns a reference to the GSource instance. However, it
is a bit verbose to use in the common case.
Add helper functions that simplify the use and are conceptionally
similar to g_{idle,timeout}_add() (hence the name).
|
||
|---|---|---|
| .. | ||
| c-list | ||
| c-rbtree | ||
| c-siphash | ||
| c-stdaux | ||
| n-acd | ||
| n-dhcp4 | ||
| nm-base | ||
| nm-glib-aux | ||
| nm-log-core | ||
| nm-platform | ||
| nm-std-aux | ||
| nm-udev-aux | ||
| nm-utils | ||
| systemd | ||
| meson.build | ||
| nm-default.h | ||
| nm-meta-setting.c | ||
| nm-meta-setting.h | ||
| nm-test-libnm-utils.h | ||
| nm-test-utils-impl.c | ||
| nm-version-macros.h.in | ||
| README.md | ||
The "shared/" Directory
For NetworkManager we place helper/utility code under "shared/" in static libraries. The idea is to avoid code duplication but also provide high quality helper functions that simplify the higher layers. In NetworkManager there are complicated parts, for example "src/nm-manager.c" is huge. On the other hand, this helper code should be simple and easy to understand, so that we can build more complex code on top of it.
As we statically link them into our binaries, they are all inherently internal API, that means they cannot be part of libnm's (libnm-core's) public API. It also means that their API/ABI is not stable.
We don't care these libraries to be minimal and contain only symbols that are
used by all users. Instead, we expect the linker to throw away unused symbols.
We achieve this by having a symbol versioning file to hide internal symbols
(which gives the linker a possibility to remove them if they are unused) and
compiling with LTO or "-Wl,--gc-sections". Let the tool solve this and not
manual organization.
Hence these libraries (and their content) are structured this way to satisfy the following questions:
-
which dependencies (libraries) do they have? That determines which other libraries can use it. For example:
-
"shared/nm-std-aux" and "shared/nm-glib-aux" both provide general purpose helpers, the difference is that the former has no dependency on glib2 library. Both these libraries are a basic dependency for many other parts of the code.
-
"shared/nm-udev-aux" has a dependency on libudev, it thus cannot be in "shared/nm-glib-aux".
-
client code also has a glib2 dependency. That means it can link with "shared/nm-std-aux" and "shared/nm-glib-aux", but must not link with "shared/nm-udev-aux" (as it has no direct udev dependenct -- although clients get it indirectly because libnm already requires it).
-
-
what is their overall purpose? As said, we rely on the linker to prune unused symbols. But in a few cases we avoid to merge different code in the same library. For example:
- "shared/nm-glib-aux" and "shared/nm-base" both only have a glib2 dependency. Hence, they could be merged. However we don't do that because "shared/nm-base" is more about NetworkManager specific code, while "shared/nm-glib-aux" is about general purpose helpers.
-
some of these libraries are forked from an upstream. They are kept separate so that we can re-import future upstream versions.
Detail
-
shared/c-list -
shared/c-rbtree -
shared/c-siphash -
shared/c-stdoux -
shared/n-acd -
shared/n-dhcp4These are forked from upstream and imported with git-subtree. They in general only have a libc dependency (or dependencies between each other).
-
shared/nm-std-auxThis contains helper code with only a libc dependency. Almost all C code depends on this library.
-
shared/nm-glib-auxLike "shared/nm-std-aux" but also has a glib2 dependency. Almost all glib2 code depends on this library.
-
shared/nm-udev/auxLike "shared/nm-glib-aux" but also has a libudev dependency. It has code related to libudev.
-
shared/systemdThese are forked from upstream systemd and imported with a script. Under "shared/systemd/src" we try to keep the sources as close to the original as possible. There is also some adapter code to make it useable for us. It has a dependency on "shared/nm-glib-aux" and will need a logging implementation for "shared/nm-glib-aux/nm-logging-fwd.h".
-
shared/nm-baseDepends on "shared/nm-glib-aux" and glib2 but it provides helper code that more about NetworkManager specifc things.
-
shared/nm-log-coreThis is the logging implementation as used by NetworkManager core ("src/"). It is also a dependency for "shared/nm-platform".
-
shared/nm-platformPlatform implementation. It depends on "shared/nm-log-core", "shared/nm-base" and "shared/nm-glib-aux".
-
Other than that, there are still a few unorganized files/directories here. These should be cleaned up.