forked from luvit/luv
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathdocs.lua
More file actions
4880 lines (4626 loc) · 173 KB
/
docs.lua
File metadata and controls
4880 lines (4626 loc) · 173 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
--- @class (exact) Doc.Type.Fun.Attrs
--- name, type, desc
--- @field [integer] [string, Doc.Type, string?]
--- @class (exact) Doc.Type.Fun
--- @field kind 'function'
--- name, type, desc
--- @field args [string, Doc.Type, string?][]
--- @class (exact) Doc.Type.Table.Attrs
--- @field extends? string
--- name, type, default, desc
--- @field [integer] [string, Doc.Type, string?, string?]
--- @class (exact) Doc.Type.Table
--- @field kind 'table'
--- @field extends? string
--- name, type, default, desc
--- @field fields [string, Doc.Type, string?, string?][]
--- @class (exact) Doc.Type.Union
--- @field kind 'union'
--- @field [1] Doc.Type[]
--- @class (exact) Doc.Type.Dict
--- @field kind 'dict'
--- @field key string key
--- @field value Doc.Type value
--- @alias Doc.Type
--- | string
--- | Doc.Type.Fun
--- | Doc.Type.Table
--- | Doc.Type.Dict
--- | Doc.Type.Union
--- @class (exact) Doc.Func.Param
--- @field name string
--- @field type Doc.Type
--- @field desc? string
--- @field default? string
--- @alias Doc.Func.Return [Doc.Type, string]
--- @class (exact) Doc.Func
--- @field name string
--- @field desc? string
--- @field deprecated? string
--- @field since? string
--- @field params? Doc.Func.Param[]
--- @field returns? string|Doc.Func.Return[]
--- @field returns_sync? string|Doc.Func.Return[]
--- @field returns_async? string|Doc.Func.Return[]
--- @field returns_doc? string
--- @field returns_sync_doc? string
--- @field notes? string[]
--- @field warnings? string[]
--- @field example? string
--- @field method_form? string
--- @field see? string
--- @class (exact) Doc
--- @field title? string
--- @field desc? string
--- @field id? string
--- @field class? string
--- @field sections? Doc[]
--- @field funcs? Doc.Func[]
--- @field constants? [string,string][]
--- @field aliases? table<string,[string,string][]>
--- @param ... Doc.Type
--- @return Doc.Type.Union
local function union(...)
return { kind = 'union', { ... } }
end
--- @param ty Doc.Type
--- @return Doc.Type.Union
local function opt(ty)
if type(ty) == 'table' and ty.kind == 'union' then
table.insert(ty[1], 'nil')
return ty
end
return union(ty, 'nil')
end
local opt_str = opt('string')
local opt_int = opt('integer')
local opt_bool = opt('boolean')
--- @param t? Doc.Type.Table.Attrs
--- @return Doc.Type.Table
local function table(t)
t = t or {}
local extends = t.extends
t.extends = nil
return {
kind = 'table',
extends = extends,
fields = t,
}
end
--- @param key Doc.Type
--- @param value Doc.Type
--- @return Doc.Type.Dict
local function dict(key, value)
return {
kind = 'dict',
key = key,
value = value,
}
end
--- @param extends string
--- @return Doc.Type.Table
local function cls(extends)
return table({ extends = extends })
end
--- @param ty Doc.Type
--- @param name string
--- @return [Doc.Type, string][]
local function ret_or_fail(ty, name)
return {
{ opt(ty), name },
{ opt_str, 'err' },
{ opt('uv.error_name'), 'err_name' },
}
end
--- @param t Doc.Type.Fun.Attrs
--- @return Doc.Type.Fun
local function fun(t)
return {
kind = 'function',
args = t,
}
end
--- @param args? [string, Doc.Type, string?][]
--- @param optional? boolean
--- @param desc? string
--- @return Doc.Func.Param
local function cb(args, optional, desc)
--- @type Doc.Type
local ty = fun(args or {})
if optional then
ty = opt(ty)
end
return {
name = 'callback',
type = ty,
desc = desc,
}
end
--- @param args? [string, Doc.Type, string?][]
--- @param optional? boolean
--- @param desc? string
--- @return Doc.Func.Param
local function cb_err(args, optional, desc)
return cb({
{ 'err', opt_str },
(_G.table.unpack or unpack)(args or {}),
}, optional, desc)
end
--- @param args? [string, Doc.Type, string?][]
--- @return Doc.Func.Param
local function async_cb(args)
args = args or { { 'success', opt_bool } }
return cb_err(args, true, '(async if provided, sync if `nil`)')
end
local success_ret = ret_or_fail('0', 'success')
local error_names = {
{ 'E2BIG', 'argument list too long.' },
{ 'EACCES', 'permission denied.' },
{ 'EADDRINUSE', 'address already in use.' },
{ 'EADDRNOTAVAIL', 'address not available.' },
{ 'EAFNOSUPPORT', 'address family not supported.' },
{ 'EAGAIN', 'resource temporarily unavailable.' },
{ 'EAI_ADDRFAMILY', 'address family not supported.' },
{ 'EAI_AGAIN', 'temporary failure.' },
{ 'EAI_BADFLAGS', 'bad ai_flags value.' },
{ 'EAI_BADHINTS', 'invalid value for hints.' },
{ 'EAI_CANCELED', 'request canceled.' },
{ 'EAI_FAIL', 'permanent failure.' },
{ 'EAI_FAMILY', 'ai_family not supported.' },
{ 'EAI_MEMORY', 'out of memory.' },
{ 'EAI_NODATA', 'no address.' },
{ 'EAI_NONAME', 'unknown node or service.' },
{ 'EAI_OVERFLOW', 'argument buffer overflow.' },
{ 'EAI_PROTOCOL', 'resolved protocol is unknown.' },
{ 'EAI_SERVICE', 'service not available for socket type.' },
{ 'EAI_SOCKTYPE', 'socket type not supported.' },
{ 'EALREADY', 'connection already in progress.' },
{ 'EBADF', 'bad file descriptor.' },
{ 'EBUSY', 'resource busy or locked.' },
{ 'ECANCELED', 'operation canceled.' },
{ 'ECHARSET', 'invalid Unicode character.' },
{ 'ECONNABORTED', 'software caused connection abort.' },
{ 'ECONNREFUSED', 'connection refused.' },
{ 'ECONNRESET', 'connection reset by peer.' },
{ 'EDESTADDRREQ', 'destination address required.' },
{ 'EEXIST', 'file already exists.' },
{ 'EFAULT', 'bad address in system call argument.' },
{ 'EFBIG', 'file too large.' },
{ 'EHOSTUNREACH', 'host is unreachable.' },
{ 'EINTR', 'interrupted system call.' },
{ 'EINVAL', 'invalid argument.' },
{ 'EIO', 'i/o error.' },
{ 'EISCONN', 'socket is already connected.' },
{ 'EISDIR', 'illegal operation on a directory.' },
{ 'ELOOP', 'too many symbolic links encountered.' },
{ 'EMFILE', 'too many open files.' },
{ 'EMSGSIZE', 'message too long.' },
{ 'ENAMETOOLONG', 'name too long.' },
{ 'ENETDOWN', 'network is down.' },
{ 'ENETUNREACH', 'network is unreachable.' },
{ 'ENFILE', 'file table overflow.' },
{ 'ENOBUFS', 'no buffer space available.' },
{ 'ENODEV', 'no such device.' },
{ 'ENOENT', 'no such file or directory.' },
{ 'ENOMEM', 'not enough memory.' },
{ 'ENONET', 'machine is not on the network.' },
{ 'ENOPROTOOPT', 'protocol not available.' },
{ 'ENOSPC', 'no space left on device.' },
{ 'ENOSYS', 'function not implemented.' },
{ 'ENOTCONN', 'socket is not connected.' },
{ 'ENOTDIR', 'not a directory.' },
{ 'ENOTEMPTY', 'directory not empty.' },
{ 'ENOTSOCK', 'socket operation on non-socket.' },
{ 'ENOTSUP', 'operation not supported on socket.' },
{ 'EOVERFLOW', 'value too large for defined data type.' },
{ 'EPERM', 'operation not permitted.' },
{ 'EPIPE', 'broken pipe.' },
{ 'EPROTO', 'protocol error.' },
{ 'EPROTONOSUPPORT', 'protocol not supported.' },
{ 'EPROTOTYPE', 'protocol wrong type for socket.' },
{ 'ERANGE', 'result too large.' },
{ 'EROFS', 'read-only file system.' },
{ 'ESHUTDOWN', 'cannot send after transport endpoint shutdown.' },
{ 'ESPIPE', 'invalid seek.' },
{ 'ESRCH', 'no such process.' },
{ 'ETIMEDOUT', 'connection timed out.' },
{ 'ETXTBSY', 'text file is busy.' },
{ 'EXDEV', 'cross-device link not permitted.' },
{ 'UNKNOWN', 'unknown error.' },
{ 'EOF', 'end of file.' },
{ 'ENXIO', 'no such device or address.' },
{ 'EMLINK', 'too many links.' },
{ 'ENOTTY', 'inappropriate ioctl for device.' },
{ 'EFTYPE', 'inappropriate file type or format.' },
{ 'EILSEQ', 'illegal byte sequence.' },
{ 'ESOCKTNOSUPPORT', 'socket type not supported.' },
}
--- @type table<string,[string,string][]>
local constants = {
address_families = {
{ 'AF_UNIX', 'unix' },
{ 'AF_INET', 'inet' },
{ 'AF_INET6', 'inet6' },
{ 'AF_IPX', 'ipx' },
{ 'AF_NETLINK', 'netlink' },
{ 'AF_X25', 'x25' },
{ 'AF_AX25', 'as25' },
{ 'AF_ATMPVC', 'atmpvc' },
{ 'AF_APPLETALK', 'appletalk' },
{ 'AF_PACKET', 'packet' },
},
signals = {
{ 'SIGHUP', 'sighup' },
{ 'SIGINT', 'sigint' },
{ 'SIGQUIT', 'sigquit' },
{ 'SIGILL', 'sigill' },
{ 'SIGTRAP', 'sigtrap' },
{ 'SIGABRT', 'sigabrt' },
{ 'SIGIOT', 'sigiot' },
{ 'SIGBUS', 'sigbus' },
{ 'SIGFPE', 'sigfpe' },
{ 'SIGKILL', 'sigkill' },
{ 'SIGUSR1', 'sigusr1' },
{ 'SIGSEGV', 'sigsegv' },
{ 'SIGUSR2', 'sigusr2' },
{ 'SIGPIPE', 'sigpipe' },
{ 'SIGALRM', 'sigalrm' },
{ 'SIGTERM', 'sigterm' },
{ 'SIGCHLD', 'sigchld' },
{ 'SIGSTKFLT', 'sigstkflt' },
{ 'SIGCONT', 'sigcont' },
{ 'SIGSTOP', 'sigstop' },
{ 'SIGTSTP', 'sigtstp' },
{ 'SIGBREAK', 'sigbreak' },
{ 'SIGTTIN', 'sigttin' },
{ 'SIGTTOU', 'sigttou' },
{ 'SIGURG', 'sigurg' },
{ 'SIGXCPU', 'sigxcpu' },
{ 'SIGXFSZ', 'sigxfsz' },
{ 'SIGVTALRM', 'sigvtalrm' },
{ 'SIGPROF', 'sigprof' },
{ 'SIGWINCH', 'sigwinch' },
{ 'SIGIO', 'sigio' },
{ 'SIGPOLL', 'sigpoll' },
{ 'SIGLOST', 'siglost' },
{ 'SIGPWR', 'sigpwr' },
{ 'SIGSYS', 'sigsys' },
},
socket_types = {
{ 'SOCK_STREAM', 'stream' },
{ 'SOCK_DGRAM', 'dgram' },
{ 'SOCK_SEQPACKET', 'seqpacket' },
{ 'SOCK_RAW', 'raw' },
{ 'SOCK_RDM', 'rdm' },
},
tty_modes = {
{ 'TTY_MODE_NORMAL', 'normal' },
{ 'TTY_MODE_RAW', 'raw' },
{ 'TTY_MODE_IO', 'io' },
{ 'TTY_MODE_RAW_VT', 'raw_vt' },
},
fs_utime = {
{ 'FS_UTIME_NOW', 'now' },
{ 'FS_UTIME_OMIT', 'omit' },
},
}
--- @type table<string,Doc.Type>
local types = {
-- Request types
uv_req_t = cls('userdata'),
uv_connect_t = cls('uv_req_t'),
uv_fs_t = cls('uv_req_t'),
uv_getaddrinfo_t = cls('uv_req_t'),
uv_getnameinfo_t = cls('uv_req_t'),
uv_shutdown_t = cls('uv_req_t'),
uv_udp_send_t = cls('uv_req_t'),
uv_work_t = cls('uv_req_t'),
uv_write_t = cls('uv_req_t'),
-- Handle types
uv_handle_t = cls('userdata'),
uv_async_t = cls('uv_handle_t'),
uv_check_t = cls('uv_handle_t'),
uv_fs_event_t = cls('uv_handle_t'),
uv_fs_poll_t = cls('uv_handle_t'),
uv_idle_t = cls('uv_handle_t'),
uv_poll_t = cls('uv_handle_t'),
uv_prepare_t = cls('uv_handle_t'),
uv_process_t = cls('uv_handle_t'),
uv_signal_t = cls('uv_handle_t'),
uv_timer_t = cls('uv_handle_t'),
uv_udp_t = cls('uv_handle_t'),
-- Stream types
uv_stream_t = cls('uv_handle_t'),
uv_pipe_t = cls('uv_stream_t'),
uv_tty_t = cls('uv_stream_t'),
uv_tcp_t = cls('uv_stream_t'),
luv_dir_t = cls('userdata'),
luv_work_ctx_t = cls('userdata'),
luv_thread_t = cls('userdata'),
luv_sem_t = cls('userdata'),
threadargs = union('number', 'boolean', 'string', 'userdata'),
buffer = union('string', 'string[]'),
address = table({
{ 'addr', 'string' },
{ 'family', 'string' },
{ 'port', opt_int },
{ 'socktype', 'string' },
{ 'protocol', 'string' },
{ 'canonname', opt_str },
}),
socketinfo = table({
{ 'ip', 'string' },
{ 'family', 'string' },
{ 'port', 'integer' },
}),
['fs_stat.result.time'] = table({
{ 'sec', 'integer' },
{ 'nsec', 'integer' },
}),
['fs_stat.result'] = table({
{ 'dev', 'integer' },
{ 'mode', 'integer' },
{ 'nlink', 'integer' },
{ 'uid', 'integer' },
{ 'gid', 'integer' },
{ 'rdev', 'integer' },
{ 'ino', 'integer' },
{ 'size', 'integer' },
{ 'blksize', 'integer' },
{ 'blocks', 'integer' },
{ 'flags', 'integer' },
{ 'gen', 'integer' },
{ 'atime', 'fs_stat.result.time' },
{ 'mtime', 'fs_stat.result.time' },
{ 'ctime', 'fs_stat.result.time' },
{ 'birthtime', 'fs_stat.result.time' },
{ 'type', 'string' },
}),
['fs_statfs.result'] = table({
{ 'type', 'integer' },
{ 'bsize', 'integer' },
{ 'blocks', 'integer' },
{ 'bfree', 'integer' },
{ 'bavail', 'integer' },
{ 'files', 'integer' },
{ 'ffree', 'integer' },
{ 'frsize', opt('integer') },
}),
['getrusage.result.time'] = table({
{ 'sec', 'integer' },
{ 'usec', 'integer' },
}),
['getrusage.result'] = table({
{ 'utime', 'getrusage.result.time', nil, '(user CPU time used)' },
{ 'stime', 'getrusage.result.time', nil, '(system CPU time used)' },
{ 'maxrss', 'integer', nil, '(maximum resident set size)' },
{ 'ixrss', 'integer', nil, '(integral shared memory size)' },
{ 'idrss', 'integer', nil, '(integral unshared data size)' },
{ 'isrss', 'integer', nil, '(integral unshared stack size)' },
{ 'minflt', 'integer', nil, '(page reclaims (soft page faults))' },
{ 'majflt', 'integer', nil, '(page faults (hard page faults))' },
{ 'nswap', 'integer', nil, '(swaps)' },
{ 'inblock', 'integer', nil, '(block input operations)' },
{ 'oublock', 'integer', nil, '(block output operations)' },
{ 'msgsnd', 'integer', nil, '(IPC messages sent)' },
{ 'msgrcv', 'integer', nil, '(IPC messages received)' },
{ 'nsignals', 'integer', nil, '(signals received)' },
{ 'nvcsw', 'integer', nil, '(voluntary context switches)' },
{ 'nivcsw', 'integer', nil, '(involuntary context switches)' },
}),
}
--- @type Doc
local doc = {
title = 'LibUV in Lua',
desc = [[
The [luv][] project provides access to the multi-platform support library
[libuv][] in Lua code. It was primarily developed for the [luvit][] project as
the built-in `uv` module, but can be used in other Lua environments.
More information about the core libuv library can be found at the original
[libuv documentation page][].
]],
sections = {
{ -- lvl 3 sections
sections = {
{
title = 'TCP Echo Server Example',
desc = [[
Here is a small example showing a TCP echo server:
```lua
local uv = require("luv") -- "luv" when stand-alone, "uv" in luvi apps
local server = uv.new_tcp()
server:bind("127.0.0.1", 1337)
server:listen(128, function (err)
assert(not err, err)
local client = uv.new_tcp()
server:accept(client)
client:read_start(function (err, chunk)
assert(not err, err)
if chunk then
client:write(chunk)
else
client:shutdown()
client:close()
end
end)
end)
print("TCP server listening at 127.0.0.1 port 1337")
uv.run() -- an explicit run call is necessary outside of luvit
```
]],
},
{
title = 'Module Layout',
desc = [[
The luv library contains a single Lua module referred to hereafter as `uv` for
simplicity. This module consists mostly of functions with names corresponding to
their original libuv versions. For example, the libuv function `uv_tcp_bind` has
a luv version at `uv.tcp_bind`. Currently, only two non-function fields exists:
`uv.constants` and `uv.errno`, which are tables.
]],
},
{
title = 'Functions vs Methods',
desc = [[
In addition to having simple functions, luv provides an optional method-style
API. For example, `uv.tcp_bind(server, host, port)` can alternatively be called
as `server:bind(host, port)`. Note that the first argument `server` becomes the
object and `tcp_` is removed from the function name. Method forms are
documented below where they exist.
]],
},
{
title = 'Synchronous vs Asynchronous Functions',
desc = [[
Functions that accept a callback are asynchronous. These functions may
immediately return results to the caller to indicate their initial status, but
their final execution is deferred until at least the next libuv loop iteration.
After completion, their callbacks are executed with any results passed to it.
Functions that do not accept a callback are synchronous. These functions
immediately return their results to the caller.
Some (generally FS and DNS) functions can behave either synchronously or
asynchronously. If a callback is provided to these functions, they behave
asynchronously; if no callback is provided, they behave synchronously.
]],
},
{
title = 'Pseudo-Types',
desc = [[
Some unique types are defined. These are not actual types in Lua, but they are
used here to facilitate documenting consistent behavior:
- `fail`: an assertable `nil, string, string` tuple (see [Error Handling][])
- `callable`: a `function`; or a `table` or `userdata` with a `__call`
metamethod
- `buffer`: a `string` or a sequential `table` of `string`s
- `threadargs`: variable arguments (`...`) of type `nil`, `boolean`, `number`,
`string`, or `userdata`, numbers of argument limited to 9.
]],
},
},
},
{
title = 'Contents',
desc = [[
This documentation is mostly a retelling of the [libuv API documentation][]
within the context of luv's Lua API. Low-level implementation details and
unexposed C functions and types are not documented here except for when they
are relevant to behavior seen in the Lua module.
- [Constants][]
- [Error Handling][]
- [Version Checking][]
- [`uv_loop_t`][] — Event loop
- [`uv_req_t`][] — Base request
- [`uv_handle_t`][] — Base handle
- [`uv_timer_t`][] — Timer handle
- [`uv_prepare_t`][] — Prepare handle
- [`uv_check_t`][] — Check handle
- [`uv_idle_t`][] — Idle handle
- [`uv_async_t`][] — Async handle
- [`uv_poll_t`][] — Poll handle
- [`uv_signal_t`][] — Signal handle
- [`uv_process_t`][] — Process handle
- [`uv_stream_t`][] — Stream handle
- [`uv_tcp_t`][] — TCP handle
- [`uv_pipe_t`][] — Pipe handle
- [`uv_tty_t`][] — TTY handle
- [`uv_udp_t`][] — UDP handle
- [`uv_fs_event_t`][] — FS Event handle
- [`uv_fs_poll_t`][] — FS Poll handle
- [File system operations][]
- [Thread pool work scheduling][]
- [DNS utility functions][]
- [Threading and synchronization utilities][]
- [Miscellaneous utilities][]
- [Metrics operations][]
]],
},
{
title = 'Constants',
id = 'constants',
desc = [[
As a Lua library, luv supports and encourages the use of lowercase strings to
represent options. For example:
```lua
-- signal start with string input
uv.signal_start("sigterm", function(signame)
print(signame) -- string output: "sigterm"
end)
```
However, luv also superficially exposes libuv constants in a Lua table at
`uv.constants` where its keys are uppercase constant names and their associated
values are integers defined internally by libuv. The values from this table may
be supported as function arguments, but their use may not change the output
type. For example:
```lua
-- signal start with integer input
uv.signal_start(uv.constants.SIGTERM, function(signame)
print(signame) -- string output: "sigterm"
end)
```
The uppercase constants defined in `uv.constants` that have associated
lowercase option strings are listed below.
]],
sections = {
{
title = 'Address Families',
constants = constants.address_families,
},
{
title = 'Signals',
constants = constants.signals,
},
{
title = 'Socket Types',
constants = constants.socket_types,
},
{
title = 'TTY Modes',
constants = constants.tty_modes,
},
{
title = 'FS Modification Times',
constants = constants.fs_utime,
},
},
},
{
title = 'Error Handling',
id = 'error-handling',
desc = [[
In libuv, errors are represented by negative numbered constants. While these
constants are made available in the `uv.errno` table, they are not returned by
luv functions and the libuv functions used to handle them are not exposed.
Instead, if an internal error is encountered, the failing luv function will
return to the caller an assertable `nil, err, name` tuple:
- `nil` idiomatically indicates failure
- `err` is a string with the format `{name}: {message}`
- `{name}` is the error name provided internally by `uv_err_name`
- `{message}` is a human-readable message provided internally by `uv_strerror`
- `name` is the same string used to construct `err`
This tuple is referred to below as the `fail` pseudo-type.
When a function is called successfully, it will return either a value that is
relevant to the operation of the function, or the integer `0` to indicate
success, or sometimes nothing at all. These cases are documented below.
Below is a list of known error names and error strings. See libuv's
[error constants][] page for an original source.
]],
aliases = { error_name = error_names },
},
{
title = 'Version Checking',
id = 'version-checking',
funcs = {
{
name = 'version',
desc = [[
Returns the libuv version packed into a single integer. 8 bits are used for each
component, with the patch number stored in the 8 least significant bits. For
example, this would be 0x010203 in libuv 1.2.3.
]],
returns = 'integer',
},
{
name = 'version_string',
desc = [[
Returns the libuv version number as a string. For example, this would be "1.2.3"
in libuv 1.2.3. For non-release versions, the version suffix is included.
]],
returns = 'string',
},
},
},
{
title = '`uv_loop_t` - Event loop',
id = 'uv_loop_t--event-loop',
desc = [[
The event loop is the central part of libuv's functionality. It takes care of
polling for I/O and scheduling callbacks to be run based on different sources of
events.
In luv, there is an implicit uv loop for every Lua state that loads the library.
You can use this library in an multi-threaded environment as long as each thread
has it's own Lua state with its corresponding own uv loop. This loop is not
directly exposed to users in the Lua module.
]],
funcs = {
{
name = 'loop_close',
desc = [[
Closes all internal loop resources. In normal execution, the loop will
automatically be closed when it is garbage collected by Lua, so it is not
necessary to explicitly call `loop_close()`. Call this function only after the
loop has finished executing and all open handles and requests have been closed,
or it will return `EBUSY`.
]],
returns = success_ret,
},
{
name = 'run',
desc = [[
This function runs the event loop. It will act differently depending on the
specified mode:
- `"default"`: Runs the event loop until there are no more active and
referenced handles or requests. Returns `true` if `uv.stop()` was called and
there are still active handles or requests. Returns `false` in all other
cases.
- `"once"`: Poll for I/O once. Note that this function blocks if there are no
pending callbacks. Returns `false` when done (no active handles or requests
left), or `true` if more callbacks are expected (meaning you should run the
event loop again sometime in the future).
- `"nowait"`: Poll for I/O once but don't block if there are no pending
callbacks. Returns `false` if done (no active handles or requests left),
or `true` if more callbacks are expected (meaning you should run the event
loop again sometime in the future).
]],
notes = {
[[
Luvit will implicitly call `uv.run()` after loading user code, but if
you use the luv bindings directly, you need to call this after registering
your initial set of event callbacks to start the event loop.
]],
},
params = {
{ name = 'mode', type = opt_str, default = '"default"' },
},
-- If loop is already running then returns (nil, string)
returns = ret_or_fail('boolean', 'running'),
},
{
name = 'loop_configure',
desc = [[
Set additional loop options. You should normally call this before the first call
to uv_run() unless mentioned otherwise.
Supported options:
- `"block_signal"`: Block a signal when polling for new events. The second argument
to loop_configure() is the signal name (as a lowercase string) or the signal number.
This operation is currently only implemented for `"sigprof"` signals, to suppress
unnecessary wakeups when using a sampling profiler. Requesting other signals will
fail with `EINVAL`.
- `"metrics_idle_time"`: Accumulate the amount of idle time the event loop spends
in the event provider. This option is necessary to use `metrics_idle_time()`.
An example of a valid call to this function is:
```lua
uv.loop_configure("block_signal", "sigprof")
```
]],
notes = {
[[
Be prepared to handle the `ENOSYS` error; it means the loop option is
not supported by the platform.
]],
},
params = {
{ name = 'option', type = 'string' },
{ name = '...', type = 'any', desc = 'depends on `option`' },
},
returns = success_ret,
},
{
name = 'loop_mode',
desc = [[
If the loop is running, returns a string indicating the mode in use. If the loop
is not running, `nil` is returned instead.
]],
returns = { { opt_str } },
},
{
name = 'loop_alive',
desc = [[
Returns `true` if there are referenced active handles, active requests, or
closing handles in the loop; otherwise, `false`.
]],
returns = ret_or_fail('boolean', 'alive'),
},
{
name = 'stop',
desc = [[
Stop the event loop, causing `uv.run()` to end as soon as possible. This
will happen not sooner than the next loop iteration. If this function was called
before blocking for I/O, the loop won't block for I/O on this iteration.
]],
},
{
name = 'backend_fd',
desc = [[
Get backend file descriptor. Only kqueue, epoll, and event ports are supported.
This can be used in conjunction with `uv.run("nowait")` to poll in one thread
and run the event loop's callbacks in another
]],
notes = {
[[
Embedding a kqueue fd in another kqueue pollset doesn't work on all
platforms. It's not an error to add the fd but it never generates events.
]],
},
returns = { { opt_int } },
},
{
name = 'backend_timeout',
desc = [[
Get the poll timeout. The return value is in milliseconds, or -1 for no timeout.
]],
returns = 'integer',
},
{
name = 'now',
desc = [[
Returns the current timestamp in milliseconds. The timestamp is cached at the
start of the event loop tick, see `uv.update_time()` for details and rationale.
The timestamp increases monotonically from some arbitrary point in time. Don't
make assumptions about the starting point, you will only get disappointed.
]],
notes = {
'Use `uv.hrtime()` if you need sub-millisecond granularity.',
},
returns = 'integer',
},
{
name = 'update_time',
desc = [[
Update the event loop's concept of "now". Libuv caches the current time at the
start of the event loop tick in order to reduce the number of time-related
system calls.
You won't normally need to call this function unless you have callbacks that
block the event loop for longer periods of time, where "longer" is somewhat
subjective but probably on the order of a millisecond or more.
]],
},
{
name = 'walk',
desc = [[
Walk the list of handles: `callback` will be executed with each handle.
]],
example = [[
```lua
-- Example usage of uv.walk to close all handles that aren't already closing.
uv.walk(function (handle)
if not handle:is_closing() then
handle:close()
end
end)
```
]],
params = {
cb({ { 'handle', 'uv_handle_t' } }),
},
},
},
},
{
title = '`uv_req_t` - Base request',
id = 'uv_req_t--base-request',
class = 'uv_req_t',
desc = '`uv_req_t` is the base type for all libuv request types.',
funcs = {
{
name = 'cancel',
method_form = 'req:cancel()',
desc = [[
Cancel a pending request. Fails if the request is executing or has finished
executing. Only cancellation of `uv_fs_t`, `uv_getaddrinfo_t`,
`uv_getnameinfo_t` and `uv_work_t` requests is currently supported.
]],
params = {
{ name = 'req', type = 'uv_req_t' },
},
returns = success_ret,
},
{
name = 'req_get_type',
method_form = 'req:get_type()',
desc = [[
Returns the name of the struct for a given request (e.g. `"fs"` for `uv_fs_t`)
and the libuv enum integer for the request's type (`uv_req_type`).
]],
params = {
{ name = 'req', type = 'uv_req_t' },
},
returns = {
{ 'string', 'type' },
{ 'integer', 'enum' },
},
},
},
},
{
title = '`uv_handle_t` - Base handle',
id = 'uv_handle_t--base-handle',
class = 'uv_handle_t',
desc = [[
`uv_handle_t` is the base type for all libuv handle types. All API functions
defined here work with any handle type.
]],
funcs = {
{
name = 'is_active',
method_form = 'handle:is_active()',
desc = [[
Returns `true` if the handle is active, `false` if it's inactive. What "active”
means depends on the type of handle:
- A [`uv_async_t`][] handle is always active and cannot be deactivated, except
by closing it with `uv.close()`.
- A [`uv_pipe_t`][], [`uv_tcp_t`][], [`uv_udp_t`][], etc. handle - basically
any handle that deals with I/O - is active when it is doing something that
involves I/O, like reading, writing, connecting, accepting new connections,
etc.
- A [`uv_check_t`][], [`uv_idle_t`][], [`uv_timer_t`][], etc. handle is active
when it has been started with a call to `uv.check_start()`, `uv.idle_start()`,
`uv.timer_start()` etc. until it has been stopped with a call to its
respective stop function.
]],
params = {
{ name = 'handle', type = 'uv_handle_t' },
},
returns = ret_or_fail('boolean', 'active'),
},
{
name = 'is_closing',
method_form = 'handle:is_closing()',
desc = [[
Returns `true` if the handle is closing or closed, `false` otherwise.
]],
notes = {
[[
This function should only be used between the initialization of the
handle and the arrival of the close callback.
]],
},
params = {
{ name = 'handle', type = 'uv_handle_t' },
},
returns = ret_or_fail('boolean', 'closing'),
},
{
name = 'close',
method_form = 'handle:close([callback])',
desc = [[
Request handle to be closed. `callback` will be called asynchronously after this
call. This MUST be called on each handle before memory is released.
Handles that wrap file descriptors are closed immediately but `callback` will
still be deferred to the next iteration of the event loop. It gives you a chance
to free up any resources associated with the handle.
In-progress requests, like `uv_connect_t` or `uv_write_t`, are cancelled and
have their callbacks called asynchronously with `ECANCELED`.
]],
params = {
{ name = 'handle', type = 'uv_handle_t' },
cb(nil, true),
},
},
{
name = 'ref',
method_form = 'handle:ref()',
desc = [[
Reference the given handle. References are idempotent, that is, if a handle is
already referenced calling this function again will have no effect.
]],
see = 'Reference counting',
params = {
{ name = 'handle', type = 'uv_handle_t' },
},
},
{
name = 'unref',
method_form = 'handle:unref()',
desc = [[
Un-reference the given handle. References are idempotent, that is, if a handle
is not referenced calling this function again will have no effect.
]],
see = 'Reference counting',
params = {
{ name = 'handle', type = 'uv_handle_t' },
},