fdo-mirrors/NetworkManager
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/NetworkManager/NetworkManager.git synced 2025-12-27 17:30:09 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

l3cfg/trivial: explain commit-type in code comments

Browse source
This commit is contained in:
Thomas Haller 2021-09-29 09:24:52 +02:00
parent 8a06d66d0e
commit 17fd1e4708
No known key found for this signature in database
GPG key ID: 29C2366E4DFC5728
2 changed files with 38 additions and 3 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

21
src/core/nm-l3cfg.c
View file

@ -2842,6 +2842,20 @@ _l3_commit_on_idle_cb(gpointer user_data)
return G_SOURCE_REMOVE;
}
/* DOC(l3cfg:commit-type):
*
* Usually we don't want to call the synchronous nm_l3cfg_commit(), because
* that has side effects and might not be safe to do (depending on the current
* circumstances in which commit is called). The usually proper thing to do
* is schedule a commit on an idle handler. Use this function.
*
* During commit, the actually used commit-type (that is, the level of "how much"
* will be synced) is determined by users who register their desired commit
* type via nm_l3cfg_commit_type_register(), where always the "maxium" is used.
*
* nm_l3cfg_commit() and nm_l3cfg_commit_on_idle_schedule() also accept an additional
* commit_type argument. This acts like a one-shot registration.
*/
gboolean
nm_l3cfg_commit_on_idle_schedule(NML3Cfg *self, NML3CfgCommitType commit_type)
{
@ -2856,6 +2870,7 @@ nm_l3cfg_commit_on_idle_schedule(NML3Cfg *self, NML3CfgCommitType commit_type)
if (self->priv.p->commit_on_idle_source) {
if (self->priv.p->commit_on_idle_type < commit_type) {
/* For multiple calls, we collect the maximum "commit-type". */
_LOGT("commit on idle (scheduled) (update to %s)",
_l3_cfg_commit_type_to_string(commit_type,
sbuf_commit_type,
@ -3730,14 +3745,15 @@ _l3_commit(NML3Cfg *self, NML3CfgCommitType commit_type, gboolean is_idle)
nm_assert(self->priv.p->commit_reentrant_count == 0);
/* The actual commit type is always the maximum of what is requested
* and what is registered via nm_l3cfg_commit_type_register(). */
* and what is registered via nm_l3cfg_commit_type_register(), combined
* with the ad-hoc requested @commit_type argument. */
commit_type_auto = nm_l3cfg_commit_type_get(self);
if (commit_type == NM_L3_CFG_COMMIT_TYPE_AUTO || commit_type_auto > commit_type) {
commit_type_from_auto = TRUE;
commit_type = commit_type_auto;
}
/* UPDATE and higher are sticky. That means, when do perform such a commit
/* Levels UPDATE and higher are sticky. That means, when do perform such a commit
* type, then the next one will at least be of level "UPDATE". The idea is
* that if the current commit adds an address, then the following needs
* to do at least "UPDATE" level to remove it again. Even if in the meantime
@ -3784,6 +3800,7 @@ _l3_commit(NML3Cfg *self, NML3CfgCommitType commit_type, gboolean is_idle)
_nm_l3cfg_emit_signal_notify_simple(self, NM_L3_CONFIG_NOTIFY_TYPE_POST_COMMIT);
}
/* See DOC(l3cfg:commit-type) */
void
nm_l3cfg_commit(NML3Cfg *self, NML3CfgCommitType commit_type)
{

20
src/core/nm-l3cfg.h
View file

@ -320,7 +320,25 @@ gboolean nm_l3cfg_remove_config_all_dirty(NML3Cfg *self, gconstpointer tag);
/*****************************************************************************/
/* The numeric values of the enum matters: higher number mean more "important".
/* DOC(l3cfg:commit-type):
*
* The major idea of NML3Cfg is that independent parties can register configuration
* (NML3ConfigData via nm_l3cfg_add_config()), and then nm_l3cfg_commit() will
* actually configure it. Usually we would not call the synchronous nm_l3cfg_commit(),
* but instead nm_l3cfg_commit_on_idle_schedule().
*
* We have different levels of "how much" we should sync during commit. That is
* NML3CfgCommitType. Since independent parties should be able to work together,
* they can only ask for their minimal required commit-type level. That means,
* during commit we will commit with the highest level of how much one of the
* users request the commit. To request a commit level, users can call
* nm_l3cfg_commit_type_register(). nm_l3cfg_commit_on_idle_schedule() also
* accepts a one-time commit-type argument.
*
* This is related to NMDevice's sys_iface_state, which we use to control whether
* to touch/assume/manage the interface.
*
* The numeric values of the enum matters: higher number mean more "important".
* E.g. "assume" tries to preserve the most settings, while "reapply" forces
* all configuration to match. */
typedef enum _nm_packed {