api: in constructor function calls, always put the returned object pointer first (or second)

Previously the returned object of constructor functions where sometimes
returned as last, sometimes as first and sometimes as second parameter.
Let's clean this up a bit. Here are the new rules:

1. The object the new object is derived from is put first, if there is any

2. The object we are creating will be returned in the next arguments

3. This is followed by any additional arguments

Rationale:

For functions that operate on an object we always put that object first.
Constructors should probably not be too different in this regard. Also,
if the additional parameters might want to use varargs which suggests to
put them last.

Note that this new scheme only applies to constructor functions, not to
all other functions. We do give a lot of freedom for those.

Note that this commit only changes the order of the new functions we
added, for old ones we accept the wrong order and leave it like that.

2 files changed, 27 insertions, 27 deletions

diff --git a/src/libsystemd/sd-event/sd-event.c b/src/libsystemd/sd-event/sd-event.c
index cda92e2604..25dfd17d40 100644
--- a/src/libsystemd/sd-event/sd-event.c
+++ b/src/libsystemd/sd-event/sd-event.c
@@ -599,11 +599,11 @@ static sd_event_source *source_new(sd_event *e, EventSourceType type) {
 
 _public_ int sd_event_add_io(
                 sd_event *e,
+                sd_event_source **ret,
                 int fd,
                 uint32_t events,
                 sd_event_io_handler_t callback,
-                void *userdata,
-                sd_event_source **ret) {
+                void *userdata) {
 
         sd_event_source *s;
         int r;
@@ -683,6 +683,7 @@ static int event_setup_timer_fd(
 
 static int event_add_time_internal(
                 sd_event *e,
+                sd_event_source **ret,
                 EventSourceType type,
                 int *timer_fd,
                 clockid_t id,
@@ -691,8 +692,7 @@ static int event_add_time_internal(
                 uint64_t usec,
                 uint64_t accuracy,
                 sd_event_time_handler_t callback,
-                void *userdata,
-                sd_event_source **ret) {
+                void *userdata) {
 
         sd_event_source *s;
         int r;
@@ -755,23 +755,23 @@ fail:
 }
 
 _public_ int sd_event_add_monotonic(sd_event *e,
+                                    sd_event_source **ret,
                                     uint64_t usec,
                                     uint64_t accuracy,
                                     sd_event_time_handler_t callback,
-                                    void *userdata,
-                                    sd_event_source **ret) {
+                                    void *userdata) {
 
-        return event_add_time_internal(e, SOURCE_MONOTONIC, &e->monotonic_fd, CLOCK_MONOTONIC, &e->monotonic_earliest, &e->monotonic_latest, usec, accuracy, callback, userdata, ret);
+        return event_add_time_internal(e, ret, SOURCE_MONOTONIC, &e->monotonic_fd, CLOCK_MONOTONIC, &e->monotonic_earliest, &e->monotonic_latest, usec, accuracy, callback, userdata);
 }
 
 _public_ int sd_event_add_realtime(sd_event *e,
+                                   sd_event_source **ret,
                                    uint64_t usec,
                                    uint64_t accuracy,
                                    sd_event_time_handler_t callback,
-                                   void *userdata,
-                                   sd_event_source **ret) {
+                                   void *userdata) {
 
-        return event_add_time_internal(e, SOURCE_REALTIME, &e->realtime_fd, CLOCK_REALTIME, &e->realtime_earliest, &e->monotonic_latest, usec, accuracy, callback, userdata, ret);
+        return event_add_time_internal(e, ret, SOURCE_REALTIME, &e->realtime_fd, CLOCK_REALTIME, &e->realtime_earliest, &e->monotonic_latest, usec, accuracy, callback, userdata);
 }
 
 static int event_update_signal_fd(sd_event *e) {
@@ -808,10 +808,10 @@ static int event_update_signal_fd(sd_event *e) {
 
 _public_ int sd_event_add_signal(
                 sd_event *e,
+                sd_event_source **ret,
                 int sig,
                 sd_event_signal_handler_t callback,
-                void *userdata,
-                sd_event_source **ret) {
+                void *userdata) {
 
         sd_event_source *s;
         sigset_t ss;
@@ -865,11 +865,11 @@ _public_ int sd_event_add_signal(
 
 _public_ int sd_event_add_child(
                 sd_event *e,
+                sd_event_source **ret,
                 pid_t pid,
                 int options,
                 sd_event_child_handler_t callback,
-                void *userdata,
-                sd_event_source **ret) {
+                void *userdata) {
 
         sd_event_source *s;
         int r;
@@ -926,9 +926,9 @@ _public_ int sd_event_add_child(
 
 _public_ int sd_event_add_defer(
                 sd_event *e,
+                sd_event_source **ret,
                 sd_event_handler_t callback,
-                void *userdata,
-                sd_event_source **ret) {
+                void *userdata) {
 
         sd_event_source *s;
         int r;
@@ -959,9 +959,9 @@ _public_ int sd_event_add_defer(
 
 _public_ int sd_event_add_exit(
                 sd_event *e,
+                sd_event_source **ret,
                 sd_event_handler_t callback,
-                void *userdata,
-                sd_event_source **ret) {
+                void *userdata) {
 
         sd_event_source *s;
         int r;
diff --git a/src/libsystemd/sd-event/test-event.c b/src/libsystemd/sd-event/test-event.c
index c10aa8caa7..0b7e2e48c4 100644
--- a/src/libsystemd/sd-event/test-event.c
+++ b/src/libsystemd/sd-event/test-event.c
@@ -97,7 +97,7 @@ static int signal_handler(sd_event_source *s, const struct signalfd_siginfo *si,
         if (pid == 0)
                 _exit(0);
 
-        assert_se(sd_event_add_child(sd_event_source_get_event(s), pid, WEXITED, child_handler, INT_TO_PTR('f'), &p) >= 0);
+        assert_se(sd_event_add_child(sd_event_source_get_event(s), &p, pid, WEXITED, child_handler, INT_TO_PTR('f')) >= 0);
         assert_se(sd_event_source_set_enabled(p, SD_EVENT_ONESHOT) >= 0);
 
         sd_event_source_unref(s);
@@ -118,7 +118,7 @@ static int defer_handler(sd_event_source *s, void *userdata) {
         assert_se(sigemptyset(&ss) >= 0);
         assert_se(sigaddset(&ss, SIGUSR1) >= 0);
         assert_se(sigprocmask(SIG_BLOCK, &ss, NULL) >= 0);
-        assert_se(sd_event_add_signal(sd_event_source_get_event(s), SIGUSR1, signal_handler, INT_TO_PTR('e'), &p) >= 0);
+        assert_se(sd_event_add_signal(sd_event_source_get_event(s), &p, SIGUSR1, signal_handler, INT_TO_PTR('e')) >= 0);
         assert_se(sd_event_source_set_enabled(p, SD_EVENT_ONESHOT) >= 0);
         raise(SIGUSR1);
 
@@ -137,7 +137,7 @@ static int time_handler(sd_event_source *s, uint64_t usec, void *userdata) {
                 if (do_quit) {
                         sd_event_source *p;
 
-                        assert_se(sd_event_add_defer(sd_event_source_get_event(s), defer_handler, INT_TO_PTR('d'), &p) >= 0);
+                        assert_se(sd_event_add_defer(sd_event_source_get_event(s), &p, defer_handler, INT_TO_PTR('d')) >= 0);
                         assert_se(sd_event_source_set_enabled(p, SD_EVENT_ONESHOT) >= 0);
                 } else {
                         assert(!got_c);
@@ -176,7 +176,7 @@ int main(int argc, char *argv[]) {
 
         /* Test whether we cleanly can destroy an io event source from its own handler */
         got_unref = false;
-        assert_se(sd_event_add_io(e, k[0], EPOLLIN, unref_handler, NULL, &t) >= 0);
+        assert_se(sd_event_add_io(e, &t, k[0], EPOLLIN, unref_handler, NULL) >= 0);
         assert_se(write(k[1], &ch, 1) == 1);
         assert_se(sd_event_run(e, (uint64_t) -1) >= 1);
         assert_se(got_unref);
@@ -185,7 +185,7 @@ int main(int argc, char *argv[]) {
 
         /* Add a oneshot handler, trigger it, re-enable it, and trigger
          * it again. */
-        assert_se(sd_event_add_io(e, d[0], EPOLLIN, io_handler, INT_TO_PTR('d'), &w) >= 0);
+        assert_se(sd_event_add_io(e, &w, d[0], EPOLLIN, io_handler, INT_TO_PTR('d')) >= 0);
         assert_se(sd_event_source_set_enabled(w, SD_EVENT_ONESHOT) >= 0);
         assert_se(write(d[1], &ch, 1) >= 0);
         assert_se(sd_event_run(e, (uint64_t) -1) >= 1);
@@ -194,10 +194,10 @@ int main(int argc, char *argv[]) {
         assert_se(sd_event_run(e, (uint64_t) -1) >= 1);
         assert_se(got_d == 2);
 
-        assert_se(sd_event_add_io(e, a[0], EPOLLIN, io_handler, INT_TO_PTR('a'), &x) >= 0);
-        assert_se(sd_event_add_io(e, b[0], EPOLLIN, io_handler, INT_TO_PTR('b'), &y) >= 0);
-        assert_se(sd_event_add_monotonic(e, 0, 0, time_handler, INT_TO_PTR('c'), &z) >= 0);
-        assert_se(sd_event_add_exit(e, exit_handler, INT_TO_PTR('g'), &q) >= 0);
+        assert_se(sd_event_add_io(e, &x, a[0], EPOLLIN, io_handler, INT_TO_PTR('a')) >= 0);
+        assert_se(sd_event_add_io(e, &y, b[0], EPOLLIN, io_handler, INT_TO_PTR('b')) >= 0);
+        assert_se(sd_event_add_monotonic(e, &z, 0, 0, time_handler, INT_TO_PTR('c')) >= 0);
+        assert_se(sd_event_add_exit(e, &q, exit_handler, INT_TO_PTR('g')) >= 0);
 
         assert_se(sd_event_source_set_priority(x, 99) >= 0);
         assert_se(sd_event_source_set_enabled(y, SD_EVENT_ONESHOT) >= 0);