Some minor API inconsistencies

[SinisterRectus]

I'm working on a much needed update to the luv docs. It's nearly done, but I want to highlight some API inconsistencies that I found. None of these seem to be a big deal, some of them are nitpicky, but I wanted to get this list here while I have it

---

• uv.tty_set_mode accepts raw tty_set_mode_t enum instead of a lua string
• uv.getaddrinfo hints take raw integer values (I think they are in uv.constants?)

compare to:

• uv.run mode accepts lua string instead of raw uv_run_mode enum
• uv.udp_set_membership accepts lua string instead of raw uv_membership enum
• uv.poll_start accepts lua string instead of raw int for events

uv.tty_set_mode could optionally accept a string so that the change isn't breaking. Should we allow other enum-accepting functions to accept ints? Should we expose more enums at uv.constants?

---

• uv.new_tcp accepts raw int for flags
• uv.new_udp accepts raw int for flags

compare to:

• uv.tcp_bind accepts a table of booleans instead of raw int for flags
• uv.udp_bind accepts a table of booleans instead of raw int for flags
• uv.fs_event_start accepts a table of booleans instead of raw int for flags

Might be fixed? See #393 and #398.

---

• uv.getaddrinforeturns table with addr, port, family

compare to:

• uv.getnameinfo accepts table with ip, port, family
• uv.tcp_getpeername returns table with ip, port, family
• uv.tcp_getsockname returns table with ip, port, family
• uv.udp_getsockname returns table with ip, port, family
• uv.udp_getpeername returns table with ip, port, family

You can't directly use a getaddrinfo result in getnameinfo, but would you want to?

---

That's all I have for here. I'll be opening other issues or maybe PRs for things that I think deserve there own.

[squeek502]

Thanks for compiling this, I think it's really worthwhile to address this sort of stuff.

Replying to your comment in #393 here RE: new_udp/new_tcp:

The most future proof way to bind new_udp/new_tcp would be to accept a table with key "family" that can either be a string like "inet" or a raw AF_ enum integer (this matches luv_getaddrinfo), because techincally the flags param of uv_{tcp,udp}_init_ex could have more added to it in the future (right now it uses flags & 0xFF for the AF_ enum part).

Might be worth changing it to accept an integer, a string, or a table? That way it'd be easy to expand it if necessary in the future but the default would be to specify AF_ only (the current behavior).

Relevant docs:

• http://docs.libuv.org/en/v1.x/tcp.html#c.uv_tcp_init_ex
• http://docs.libuv.org/en/v1.x/udp.html#c.uv_udp_init_ex

[squeek502]

Not really an inconsistency, but something I noticed when reading through the new docs:

• uv.new_pipe's ipc argument should probably be made optional (defaulted to false) rather than required

[SinisterRectus]

misc.c returns various Lua numbers.

For these, it is fine because libuv uses a double:

• uv.uptime
• uv.loadavg

But for the rest of these, it's not clear why a Lua number is used:

Libuv returns uint64_t:

• uv.get_constrained_memory
• uv.get_total_memory
• uv.get_free_memory
• uv.hrtime

Libuv returns uv_pid_t (int on Windows, pid_t on Unix, which seems to be int on GCC)

• uv.os_getppid
• uv.os_getpid

Libuv returns int:

• uv.os_getpriority

---

uv.gettimeofday uses a Lua integer for tv_sec if __LP64__ is defined; a Lua integer is always used for tv_usec.

Libuv uses:

typedef struct {
    int64_t tv_sec;
    int32_t tv_usec;
} uv_timeval64_t;

---

uv.cpu_info uses a Lua number for every table field (except model).

Libuv uses:

typedef struct uv_cpu_info_s {
    char* model;
    int speed;
    struct uv_cpu_times_s {
        uint64_t user;
        uint64_t nice;
        uint64_t sys;
        uint64_t idle;
        uint64_t irq;
    } cpu_times;
} uv_cpu_info_t;

[squeek502]

returning Lua numbers instead of integers
uint64_t

Isn't this a more general problem? PUC Lua doesn't have the concept of uint64 at all, does it? lua_Integer is a signed integer (ptrdiff_t).

[SinisterRectus]

Hmmm good point. There's no guarantee that a Lua integer is 64 bits or unsigned.