fdo-mirrors/NetworkManager
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/NetworkManager/NetworkManager.git synced 2026-05-18 22:08:08 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions
NetworkManager/src/libnm-glib-aux/nm-ref-string.h

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

189 lines
4.6 KiB
C
Raw Normal View History

all: update deprecated SPDX license identifiers These SPDX license identifiers are deprecated ([1]). Update them. [1] https://spdx.org/licenses/ sed \ -e '1 s%^/\* SPDX-License-Identifier: \(GPL-2.0\|LGPL-2.1\)+ \*/$%/* SPDX-License-Identifier: \1-or-later */%' \ -e '1,2 s%^\(--\|#\|//\) SPDX-License-Identifier: \(GPL-2.0\|LGPL-2.1\)+$%\1 SPDX-License-Identifier: \2-or-later%' \ -i \ $(git grep -l SPDX-License-Identifier -- \ ':(exclude)shared/c-*/' \ ':(exclude)shared/n-*/' \ ':(exclude)shared/systemd/src' \ ':(exclude)src/systemd/src')
2020-12-23 22:21:36 +01:00
/* SPDX-License-Identifier: LGPL-2.1-or-later */
shared: add NMRefString I'd like to refactor libnm's caching. Note that cached D-Bus objects have repeated strings all over the place. For example every object will have a set of D-Bus interfaces (strings) and properties (strings) and an object path (which is referenced by other objects). We can save a lot of redundant strings by deduplicating/interning them. Also, by interning them, we can compare them using pointer equality. Add a NMRefString implementation for this. Maybe an alternative name would be NMInternedString or NMDedupString, because this string gets always interned. There is no way to create a NMRefString that is not interned. Still, NMRefString name sounds better. It is ref-counted after all. Notes: - glib has GQuark and g_intern_string(). However, such strings cannot be unrefered and are leaked indefinitely. It is thus unsuited for anything but a fixed set of well-known strings. - glib 2.58 adds GRefString, but we cannot use that because we currently still use glib 2.40. There are some differences: - GRefString is just a typedef to char. That means, the glib API exposes GRefString like regular character strings. NMRefString intentionally does that not. This makes it slightly less convenient to pass it to API that expects "const char *". But it makes it clear to the reader, that an instance is in fact a NMRefString, which means it indicates that the string is interned and can be referenced without additional copy. - GRefString can be optionally interned. That means you can only use pointer equality for comparing values if you know that the GRefString was created with g_ref_string_new_intern(). So, GRefString looks like a "const char *" pointer and even if you know it's a GRefString, you might not know whether it is interned. NMRefString is always interned, and you can always compare it using pointer equality. - In the past I already proposed a different implementation for a ref-string. That made different choices. For example NMRefString then was a typedef to "const char *", it did not support interning but deduplication (without a global cache), ref/unref was not thread safe (but then there was no global cache so that two threads could still use the API independently). The point is, there are various choices to make. GRefString, the previous NMRefString implementation and the one here, all have pros and cons. I think for the purpose where I intend NMRefString (dedup and efficient comparison), it is a preferable implementation. Ah, and of course NMRefString is an immutable string, which is a nice property.
2019-09-02 07:54:28 +02:00
#ifndef __NM_REF_STRING_H__
#define __NM_REF_STRING_H__
/*****************************************************************************/
shared: allow "NMRefString" typedef to be forward declared by naming the struct
2019-10-16 08:55:45 +02:00
typedef struct _NMRefString {
refstr: drop internal struct RefString and pack NMRefString Previously, NMRefString was the public part of the struct, while there was an internal RefString struct with private fields. That might make sense if we would need to preserve some stable ABI, but we don't because this is all internal (unstable) API. It also might make sense to hide fields, but in practice that is not necessary because the leading underscore is indicator enough that these are private fields that are not supposed to be touched (unless you really know what you do). So, drop RefString and move all fields in the public NMRefString. The advantage is that we can later inline certain trivial functions, that we otherwise couldn't. Also, drop the "str" pointer and only use the "str" array field. The pointer existed so that during nm_ref_string_new_len() we could create a lookup needle with external str pointer. That is now solved differently by using "len == G_MAXSIZE" as indicator that this is a special lookup instance. The advantage is that we save one pointer field per NMRefString, that we reduce the redundancy of the data, and that we don't need the additional indirection.
2021-03-17 13:12:46 +01:00
const gsize len;
union {
struct {
volatile int _ref_count;
const char str[];
};
struct {
/* This union field is only used during lookup by external string.
* In that case, len will be set to G_MAXSIZE, and the actual len/str values
* are set in _priv_lookup. */
gsize l_len;
const char *l_str;
} _priv_lookup;
};
shared: add NMRefString I'd like to refactor libnm's caching. Note that cached D-Bus objects have repeated strings all over the place. For example every object will have a set of D-Bus interfaces (strings) and properties (strings) and an object path (which is referenced by other objects). We can save a lot of redundant strings by deduplicating/interning them. Also, by interning them, we can compare them using pointer equality. Add a NMRefString implementation for this. Maybe an alternative name would be NMInternedString or NMDedupString, because this string gets always interned. There is no way to create a NMRefString that is not interned. Still, NMRefString name sounds better. It is ref-counted after all. Notes: - glib has GQuark and g_intern_string(). However, such strings cannot be unrefered and are leaked indefinitely. It is thus unsuited for anything but a fixed set of well-known strings. - glib 2.58 adds GRefString, but we cannot use that because we currently still use glib 2.40. There are some differences: - GRefString is just a typedef to char. That means, the glib API exposes GRefString like regular character strings. NMRefString intentionally does that not. This makes it slightly less convenient to pass it to API that expects "const char *". But it makes it clear to the reader, that an instance is in fact a NMRefString, which means it indicates that the string is interned and can be referenced without additional copy. - GRefString can be optionally interned. That means you can only use pointer equality for comparing values if you know that the GRefString was created with g_ref_string_new_intern(). So, GRefString looks like a "const char *" pointer and even if you know it's a GRefString, you might not know whether it is interned. NMRefString is always interned, and you can always compare it using pointer equality. - In the past I already proposed a different implementation for a ref-string. That made different choices. For example NMRefString then was a typedef to "const char *", it did not support interning but deduplication (without a global cache), ref/unref was not thread safe (but then there was no global cache so that two threads could still use the API independently). The point is, there are various choices to make. GRefString, the previous NMRefString implementation and the one here, all have pros and cons. I think for the purpose where I intend NMRefString (dedup and efficient comparison), it is a preferable implementation. Ah, and of course NMRefString is an immutable string, which is a nice property.
2019-09-02 07:54:28 +02:00
} NMRefString;
/*****************************************************************************/
refstr: inline nm_ref_string_{ref,unref}() In the fast path, ref/unref is just a atomic increment/decrement of an integer. Let's inline that.
2021-03-17 17:34:18 +01:00
void _nm_assert_nm_ref_string(NMRefString *rstr);
static inline void
nm_assert_nm_ref_string(NMRefString *rstr)
{
#if NM_MORE_ASSERTS
_nm_assert_nm_ref_string(rstr);
#endif
}
/*****************************************************************************/
shared: add NMRefString I'd like to refactor libnm's caching. Note that cached D-Bus objects have repeated strings all over the place. For example every object will have a set of D-Bus interfaces (strings) and properties (strings) and an object path (which is referenced by other objects). We can save a lot of redundant strings by deduplicating/interning them. Also, by interning them, we can compare them using pointer equality. Add a NMRefString implementation for this. Maybe an alternative name would be NMInternedString or NMDedupString, because this string gets always interned. There is no way to create a NMRefString that is not interned. Still, NMRefString name sounds better. It is ref-counted after all. Notes: - glib has GQuark and g_intern_string(). However, such strings cannot be unrefered and are leaked indefinitely. It is thus unsuited for anything but a fixed set of well-known strings. - glib 2.58 adds GRefString, but we cannot use that because we currently still use glib 2.40. There are some differences: - GRefString is just a typedef to char. That means, the glib API exposes GRefString like regular character strings. NMRefString intentionally does that not. This makes it slightly less convenient to pass it to API that expects "const char *". But it makes it clear to the reader, that an instance is in fact a NMRefString, which means it indicates that the string is interned and can be referenced without additional copy. - GRefString can be optionally interned. That means you can only use pointer equality for comparing values if you know that the GRefString was created with g_ref_string_new_intern(). So, GRefString looks like a "const char *" pointer and even if you know it's a GRefString, you might not know whether it is interned. NMRefString is always interned, and you can always compare it using pointer equality. - In the past I already proposed a different implementation for a ref-string. That made different choices. For example NMRefString then was a typedef to "const char *", it did not support interning but deduplication (without a global cache), ref/unref was not thread safe (but then there was no global cache so that two threads could still use the API independently). The point is, there are various choices to make. GRefString, the previous NMRefString implementation and the one here, all have pros and cons. I think for the purpose where I intend NMRefString (dedup and efficient comparison), it is a preferable implementation. Ah, and of course NMRefString is an immutable string, which is a nice property.
2019-09-02 07:54:28 +02:00
NMRefString *nm_ref_string_new_len(const char *cstr, gsize len);
static inline NMRefString *
nm_ref_string_new(const char *cstr)
{
return cstr ? nm_ref_string_new_len(cstr, strlen(cstr)) : NULL;
}
refstr: inline nm_ref_string_{ref,unref}() In the fast path, ref/unref is just a atomic increment/decrement of an integer. Let's inline that.
2021-03-17 17:34:18 +01:00
/*****************************************************************************/
static inline NMRefString *
nm_ref_string_ref(NMRefString *rstr)
{
if (rstr) {
nm_assert_nm_ref_string(rstr);
g_atomic_int_inc(&rstr->_ref_count);
}
return rstr;
}
void _nm_ref_string_unref_slow_path(NMRefString *rstr);
shared: add NMRefString I'd like to refactor libnm's caching. Note that cached D-Bus objects have repeated strings all over the place. For example every object will have a set of D-Bus interfaces (strings) and properties (strings) and an object path (which is referenced by other objects). We can save a lot of redundant strings by deduplicating/interning them. Also, by interning them, we can compare them using pointer equality. Add a NMRefString implementation for this. Maybe an alternative name would be NMInternedString or NMDedupString, because this string gets always interned. There is no way to create a NMRefString that is not interned. Still, NMRefString name sounds better. It is ref-counted after all. Notes: - glib has GQuark and g_intern_string(). However, such strings cannot be unrefered and are leaked indefinitely. It is thus unsuited for anything but a fixed set of well-known strings. - glib 2.58 adds GRefString, but we cannot use that because we currently still use glib 2.40. There are some differences: - GRefString is just a typedef to char. That means, the glib API exposes GRefString like regular character strings. NMRefString intentionally does that not. This makes it slightly less convenient to pass it to API that expects "const char *". But it makes it clear to the reader, that an instance is in fact a NMRefString, which means it indicates that the string is interned and can be referenced without additional copy. - GRefString can be optionally interned. That means you can only use pointer equality for comparing values if you know that the GRefString was created with g_ref_string_new_intern(). So, GRefString looks like a "const char *" pointer and even if you know it's a GRefString, you might not know whether it is interned. NMRefString is always interned, and you can always compare it using pointer equality. - In the past I already proposed a different implementation for a ref-string. That made different choices. For example NMRefString then was a typedef to "const char *", it did not support interning but deduplication (without a global cache), ref/unref was not thread safe (but then there was no global cache so that two threads could still use the API independently). The point is, there are various choices to make. GRefString, the previous NMRefString implementation and the one here, all have pros and cons. I think for the purpose where I intend NMRefString (dedup and efficient comparison), it is a preferable implementation. Ah, and of course NMRefString is an immutable string, which is a nice property.
2019-09-02 07:54:28 +02:00
static inline void
nm_ref_string_unref(NMRefString *rstr)
{
refstr: inline nm_ref_string_{ref,unref}() In the fast path, ref/unref is just a atomic increment/decrement of an integer. Let's inline that.
2021-03-17 17:34:18 +01:00
int r;
if (!rstr)
return;
nm_assert_nm_ref_string(rstr);
/* fast-path: first try to decrement the ref-count without bringing it
* to zero. */
r = rstr->_ref_count;
if (G_LIKELY(r > 1 && g_atomic_int_compare_and_exchange(&rstr->_ref_count, r, r - 1)))
return;
_nm_ref_string_unref_slow_path(rstr);
shared: add NMRefString I'd like to refactor libnm's caching. Note that cached D-Bus objects have repeated strings all over the place. For example every object will have a set of D-Bus interfaces (strings) and properties (strings) and an object path (which is referenced by other objects). We can save a lot of redundant strings by deduplicating/interning them. Also, by interning them, we can compare them using pointer equality. Add a NMRefString implementation for this. Maybe an alternative name would be NMInternedString or NMDedupString, because this string gets always interned. There is no way to create a NMRefString that is not interned. Still, NMRefString name sounds better. It is ref-counted after all. Notes: - glib has GQuark and g_intern_string(). However, such strings cannot be unrefered and are leaked indefinitely. It is thus unsuited for anything but a fixed set of well-known strings. - glib 2.58 adds GRefString, but we cannot use that because we currently still use glib 2.40. There are some differences: - GRefString is just a typedef to char. That means, the glib API exposes GRefString like regular character strings. NMRefString intentionally does that not. This makes it slightly less convenient to pass it to API that expects "const char *". But it makes it clear to the reader, that an instance is in fact a NMRefString, which means it indicates that the string is interned and can be referenced without additional copy. - GRefString can be optionally interned. That means you can only use pointer equality for comparing values if you know that the GRefString was created with g_ref_string_new_intern(). So, GRefString looks like a "const char *" pointer and even if you know it's a GRefString, you might not know whether it is interned. NMRefString is always interned, and you can always compare it using pointer equality. - In the past I already proposed a different implementation for a ref-string. That made different choices. For example NMRefString then was a typedef to "const char *", it did not support interning but deduplication (without a global cache), ref/unref was not thread safe (but then there was no global cache so that two threads could still use the API independently). The point is, there are various choices to make. GRefString, the previous NMRefString implementation and the one here, all have pros and cons. I think for the purpose where I intend NMRefString (dedup and efficient comparison), it is a preferable implementation. Ah, and of course NMRefString is an immutable string, which is a nice property.
2019-09-02 07:54:28 +02:00
}
refstr: inline nm_ref_string_{ref,unref}() In the fast path, ref/unref is just a atomic increment/decrement of an integer. Let's inline that.
2021-03-17 17:34:18 +01:00
NM_AUTO_DEFINE_FCN_VOID(NMRefString *, _nm_auto_ref_string, nm_ref_string_unref);
shared: add NMRefString I'd like to refactor libnm's caching. Note that cached D-Bus objects have repeated strings all over the place. For example every object will have a set of D-Bus interfaces (strings) and properties (strings) and an object path (which is referenced by other objects). We can save a lot of redundant strings by deduplicating/interning them. Also, by interning them, we can compare them using pointer equality. Add a NMRefString implementation for this. Maybe an alternative name would be NMInternedString or NMDedupString, because this string gets always interned. There is no way to create a NMRefString that is not interned. Still, NMRefString name sounds better. It is ref-counted after all. Notes: - glib has GQuark and g_intern_string(). However, such strings cannot be unrefered and are leaked indefinitely. It is thus unsuited for anything but a fixed set of well-known strings. - glib 2.58 adds GRefString, but we cannot use that because we currently still use glib 2.40. There are some differences: - GRefString is just a typedef to char. That means, the glib API exposes GRefString like regular character strings. NMRefString intentionally does that not. This makes it slightly less convenient to pass it to API that expects "const char *". But it makes it clear to the reader, that an instance is in fact a NMRefString, which means it indicates that the string is interned and can be referenced without additional copy. - GRefString can be optionally interned. That means you can only use pointer equality for comparing values if you know that the GRefString was created with g_ref_string_new_intern(). So, GRefString looks like a "const char *" pointer and even if you know it's a GRefString, you might not know whether it is interned. NMRefString is always interned, and you can always compare it using pointer equality. - In the past I already proposed a different implementation for a ref-string. That made different choices. For example NMRefString then was a typedef to "const char *", it did not support interning but deduplication (without a global cache), ref/unref was not thread safe (but then there was no global cache so that two threads could still use the API independently). The point is, there are various choices to make. GRefString, the previous NMRefString implementation and the one here, all have pros and cons. I think for the purpose where I intend NMRefString (dedup and efficient comparison), it is a preferable implementation. Ah, and of course NMRefString is an immutable string, which is a nice property.
2019-09-02 07:54:28 +02:00
#define nm_auto_ref_string nm_auto(_nm_auto_ref_string)
/*****************************************************************************/
static inline const char *
nm_ref_string_get_str(NMRefString *rstr)
{
return rstr ? rstr->str : NULL;
}
static inline gsize
nm_ref_string_get_len(NMRefString *rstr)
{
return rstr ? rstr->len : 0u;
}
glib-aux: add nm_ref_string_{equal,cmp}() helpers
2021-05-20 20:31:04 +02:00
static inline gboolean
nm_ref_string_equal(NMRefString *a, NMRefString *b)
{
return a == b;
}
static inline int
nm_ref_string_cmp(NMRefString *a, NMRefString *b)
{
NM_CMP_SELF(a, b);
/* It would be cheaper to first compare by length. But this
* way we get a nicer, ASCIIbethical sort order. */
NM_CMP_DIRECT_MEMCMP(a->str, b->str, NM_MIN(a->len, b->len));
NM_CMP_DIRECT(a->len, b->len);
return nm_assert_unreachable_val(0);
}
#define NM_CMP_DIRECT_REF_STRING(a, b) NM_CMP_RETURN_DIRECT(nm_ref_string_cmp((a), (b)))
shared: add nm_ref_string_equals_str() helper
2020-01-29 17:46:22 +01:00
static inline gboolean
glib-aux/trivial: rename nm_ref_string_equals_str() to nm_ref_string_equal_str()
2021-05-20 20:58:24 +02:00
nm_ref_string_equal_str(NMRefString *rstr, const char *str)
shared: add nm_ref_string_equals_str() helper
2020-01-29 17:46:22 +01:00
{
glib-aux: improve nm_ref_string_equals_str() to work for non-C-strings A NMRefString tracks the length seprately, it thus may not be a NUL terminated string (although, there is always a NUL character at the end of the buffer). As such, the previous implementation did not work correctly in when comparing for example NMRefString("a\0b") with "a". There was even a comment hinting to that fact. Instead of making obscure comments, fix the implementation to behave always correctly.
2021-05-20 19:05:56 +02:00
if (!str)
return (!!rstr);
if (!rstr)
return FALSE;
shared: add nm_ref_string_equals_str() helper
2020-01-29 17:46:22 +01:00
glib-aux: improve nm_ref_string_equals_str() to work for non-C-strings A NMRefString tracks the length seprately, it thus may not be a NUL terminated string (although, there is always a NUL character at the end of the buffer). As such, the previous implementation did not work correctly in when comparing for example NMRefString("a\0b") with "a". There was even a comment hinting to that fact. Instead of making obscure comments, fix the implementation to behave always correctly.
2021-05-20 19:05:56 +02:00
return rstr->len == strlen(str) && (rstr->str == str || memcmp(rstr->str, str, rstr->len) == 0);
shared: add nm_ref_string_equals_str() helper
2020-01-29 17:46:22 +01:00
}
shared: add NM_IS_REF_STRING() helper
2019-10-22 16:49:05 +02:00
static inline gboolean
refstr: drop "const" from argument of NM_IS_REF_STRING() NMRefString has only const fields itself, and all operations (except ref/unref) don't mutate the instance. As such, the type is already immutable, and using "const" is redundant and unnecessary. Drop "const" from all API of NMRefString.
2021-03-18 08:43:22 +01:00
NM_IS_REF_STRING(NMRefString *rstr)
shared: add NM_IS_REF_STRING() helper
2019-10-22 16:49:05 +02:00
{
refstr: use nm_assert_nm_ref_string() in NM_IS_REF_STRING()
2021-03-18 08:50:09 +01:00
if (rstr)
nm_assert_nm_ref_string(rstr);
shared: add NM_IS_REF_STRING() helper
2019-10-22 16:49:05 +02:00
/* Technically, %NULL is also a valid NMRefString (according to nm_ref_string_new(),
* nm_ref_string_get_str() and nm_ref_string_unref()). However, NM_IS_REF_STRING()
* does not think so. If callers want to allow %NULL, they need to check
* separately. */
return !!rstr;
}
refstr: add NM_REF_STRING_UPCAST() helper Imaging you track a list of NMRefString instances. You could directly expose them as strv array, but then you need a way from the string back to the NMRefString instance. That's easy to do. Add NM_REF_STRING_UPCAST() for that.
2021-03-17 14:05:41 +01:00
static inline NMRefString *
NM_REF_STRING_UPCAST(const char *str)
{
NMRefString *rstr;
if (!str)
return NULL;
clang-format: reformat code with clang 12 The format depends on the version of the tool. Now that Fedora 34 is released, update to clang 12 (clang-tools-extra-12.0.0-0.3.rc1.fc34.x86_64).
2021-05-03 21:48:58 +02:00
rstr = (gpointer) (((char *) str) - G_STRUCT_OFFSET(NMRefString, str));
refstr: add NM_REF_STRING_UPCAST() helper Imaging you track a list of NMRefString instances. You could directly expose them as strv array, but then you need a way from the string back to the NMRefString instance. That's easy to do. Add NM_REF_STRING_UPCAST() for that.
2021-03-17 14:05:41 +01:00
nm_assert_nm_ref_string(rstr);
return rstr;
}
glib-aux: add ref/unref function for down-cast NMRefString
2021-09-01 15:14:48 +02:00
static inline NMRefString *
nm_ref_string_ref_upcast(const char *str)
{
return nm_ref_string_ref(NM_REF_STRING_UPCAST(str));
}
static inline void
nm_ref_string_unref_upcast(const char *str)
{
nm_ref_string_unref(NM_REF_STRING_UPCAST(str));
}
glib-aux: add nm_ref_string_reset_str() helper
2021-05-20 19:06:14 +02:00
static inline gboolean
nm_ref_string_reset_str(NMRefString **ptr, const char *str)
{
nm_auto_ref_string NMRefString *rstr = NULL;
gsize l;
nm_assert(ptr);
if (!str)
return nm_clear_pointer(ptr, nm_ref_string_unref);
l = strlen(str);
if ((*ptr) && (*ptr)->len == l && ((*ptr)->str == str || memcmp((*ptr)->str, str, l) == 0))
return FALSE;
rstr = *ptr;
*ptr = nm_ref_string_new_len(str, l);
return TRUE;
}
shared: add NMRefString I'd like to refactor libnm's caching. Note that cached D-Bus objects have repeated strings all over the place. For example every object will have a set of D-Bus interfaces (strings) and properties (strings) and an object path (which is referenced by other objects). We can save a lot of redundant strings by deduplicating/interning them. Also, by interning them, we can compare them using pointer equality. Add a NMRefString implementation for this. Maybe an alternative name would be NMInternedString or NMDedupString, because this string gets always interned. There is no way to create a NMRefString that is not interned. Still, NMRefString name sounds better. It is ref-counted after all. Notes: - glib has GQuark and g_intern_string(). However, such strings cannot be unrefered and are leaked indefinitely. It is thus unsuited for anything but a fixed set of well-known strings. - glib 2.58 adds GRefString, but we cannot use that because we currently still use glib 2.40. There are some differences: - GRefString is just a typedef to char. That means, the glib API exposes GRefString like regular character strings. NMRefString intentionally does that not. This makes it slightly less convenient to pass it to API that expects "const char *". But it makes it clear to the reader, that an instance is in fact a NMRefString, which means it indicates that the string is interned and can be referenced without additional copy. - GRefString can be optionally interned. That means you can only use pointer equality for comparing values if you know that the GRefString was created with g_ref_string_new_intern(). So, GRefString looks like a "const char *" pointer and even if you know it's a GRefString, you might not know whether it is interned. NMRefString is always interned, and you can always compare it using pointer equality. - In the past I already proposed a different implementation for a ref-string. That made different choices. For example NMRefString then was a typedef to "const char *", it did not support interning but deduplication (without a global cache), ref/unref was not thread safe (but then there was no global cache so that two threads could still use the API independently). The point is, there are various choices to make. GRefString, the previous NMRefString implementation and the one here, all have pros and cons. I think for the purpose where I intend NMRefString (dedup and efficient comparison), it is a preferable implementation. Ah, and of course NMRefString is an immutable string, which is a nice property.
2019-09-02 07:54:28 +02:00
#endif /* __NM_REF_STRING_H__ */
Reference in a new issue Copy permalink