mirror of https://github.com/lukechilds/node.git
Fedor Indutny
10 years ago
committed by
Timothy J Fontaine
Timothy J Fontaine
110 changed files with 6370 additions and 1680 deletions
@ -0,0 +1,243 @@ |
|||
@ECHO OFF |
|||
|
|||
REM Command file for Sphinx documentation |
|||
|
|||
if "%SPHINXBUILD%" == "" ( |
|||
set SPHINXBUILD=sphinx-build |
|||
) |
|||
set BUILDDIR=build |
|||
set SRCDIR=src |
|||
set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% %SRCDIR% |
|||
set I18NSPHINXOPTS=%SPHINXOPTS% %SRCDIR% |
|||
if NOT "%PAPER%" == "" ( |
|||
set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% |
|||
set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% |
|||
) |
|||
|
|||
if "%1" == "" goto help |
|||
|
|||
if "%1" == "help" ( |
|||
:help |
|||
echo.Please use `make ^<target^>` where ^<target^> is one of |
|||
echo. html to make standalone HTML files |
|||
echo. dirhtml to make HTML files named index.html in directories |
|||
echo. singlehtml to make a single large HTML file |
|||
echo. pickle to make pickle files |
|||
echo. json to make JSON files |
|||
echo. htmlhelp to make HTML files and a HTML help project |
|||
echo. qthelp to make HTML files and a qthelp project |
|||
echo. devhelp to make HTML files and a Devhelp project |
|||
echo. epub to make an epub |
|||
echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter |
|||
echo. text to make text files |
|||
echo. man to make manual pages |
|||
echo. texinfo to make Texinfo files |
|||
echo. gettext to make PO message catalogs |
|||
echo. changes to make an overview over all changed/added/deprecated items |
|||
echo. xml to make Docutils-native XML files |
|||
echo. pseudoxml to make pseudoxml-XML files for display purposes |
|||
echo. linkcheck to check all external links for integrity |
|||
echo. doctest to run all doctests embedded in the documentation if enabled |
|||
goto end |
|||
) |
|||
|
|||
if "%1" == "clean" ( |
|||
for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i |
|||
del /q /s %BUILDDIR%\* |
|||
goto end |
|||
) |
|||
|
|||
|
|||
%SPHINXBUILD% 2> nul |
|||
if errorlevel 9009 ( |
|||
echo. |
|||
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx |
|||
echo.installed, then set the SPHINXBUILD environment variable to point |
|||
echo.to the full path of the 'sphinx-build' executable. Alternatively you |
|||
echo.may add the Sphinx directory to PATH. |
|||
echo. |
|||
echo.If you don't have Sphinx installed, grab it from |
|||
echo.http://sphinx-doc.org/ |
|||
exit /b 1 |
|||
) |
|||
|
|||
if "%1" == "html" ( |
|||
%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html |
|||
if errorlevel 1 exit /b 1 |
|||
echo. |
|||
echo.Build finished. The HTML pages are in %BUILDDIR%/html. |
|||
goto end |
|||
) |
|||
|
|||
if "%1" == "dirhtml" ( |
|||
%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml |
|||
if errorlevel 1 exit /b 1 |
|||
echo. |
|||
echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. |
|||
goto end |
|||
) |
|||
|
|||
if "%1" == "singlehtml" ( |
|||
%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml |
|||
if errorlevel 1 exit /b 1 |
|||
echo. |
|||
echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. |
|||
goto end |
|||
) |
|||
|
|||
if "%1" == "pickle" ( |
|||
%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle |
|||
if errorlevel 1 exit /b 1 |
|||
echo. |
|||
echo.Build finished; now you can process the pickle files. |
|||
goto end |
|||
) |
|||
|
|||
if "%1" == "json" ( |
|||
%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json |
|||
if errorlevel 1 exit /b 1 |
|||
echo. |
|||
echo.Build finished; now you can process the JSON files. |
|||
goto end |
|||
) |
|||
|
|||
if "%1" == "htmlhelp" ( |
|||
%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp |
|||
if errorlevel 1 exit /b 1 |
|||
echo. |
|||
echo.Build finished; now you can run HTML Help Workshop with the ^ |
|||
.hhp project file in %BUILDDIR%/htmlhelp. |
|||
goto end |
|||
) |
|||
|
|||
if "%1" == "qthelp" ( |
|||
%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp |
|||
if errorlevel 1 exit /b 1 |
|||
echo. |
|||
echo.Build finished; now you can run "qcollectiongenerator" with the ^ |
|||
.qhcp project file in %BUILDDIR%/qthelp, like this: |
|||
echo.^> qcollectiongenerator %BUILDDIR%\qthelp\libuv.qhcp |
|||
echo.To view the help file: |
|||
echo.^> assistant -collectionFile %BUILDDIR%\qthelp\libuv.ghc |
|||
goto end |
|||
) |
|||
|
|||
if "%1" == "devhelp" ( |
|||
%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp |
|||
if errorlevel 1 exit /b 1 |
|||
echo. |
|||
echo.Build finished. |
|||
goto end |
|||
) |
|||
|
|||
if "%1" == "epub" ( |
|||
%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub |
|||
if errorlevel 1 exit /b 1 |
|||
echo. |
|||
echo.Build finished. The epub file is in %BUILDDIR%/epub. |
|||
goto end |
|||
) |
|||
|
|||
if "%1" == "latex" ( |
|||
%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex |
|||
if errorlevel 1 exit /b 1 |
|||
echo. |
|||
echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. |
|||
goto end |
|||
) |
|||
|
|||
if "%1" == "latexpdf" ( |
|||
%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex |
|||
cd %BUILDDIR%/latex |
|||
make all-pdf |
|||
cd %BUILDDIR%/.. |
|||
echo. |
|||
echo.Build finished; the PDF files are in %BUILDDIR%/latex. |
|||
goto end |
|||
) |
|||
|
|||
if "%1" == "latexpdfja" ( |
|||
%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex |
|||
cd %BUILDDIR%/latex |
|||
make all-pdf-ja |
|||
cd %BUILDDIR%/.. |
|||
echo. |
|||
echo.Build finished; the PDF files are in %BUILDDIR%/latex. |
|||
goto end |
|||
) |
|||
|
|||
if "%1" == "text" ( |
|||
%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text |
|||
if errorlevel 1 exit /b 1 |
|||
echo. |
|||
echo.Build finished. The text files are in %BUILDDIR%/text. |
|||
goto end |
|||
) |
|||
|
|||
if "%1" == "man" ( |
|||
%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man |
|||
if errorlevel 1 exit /b 1 |
|||
echo. |
|||
echo.Build finished. The manual pages are in %BUILDDIR%/man. |
|||
goto end |
|||
) |
|||
|
|||
if "%1" == "texinfo" ( |
|||
%SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo |
|||
if errorlevel 1 exit /b 1 |
|||
echo. |
|||
echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. |
|||
goto end |
|||
) |
|||
|
|||
if "%1" == "gettext" ( |
|||
%SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale |
|||
if errorlevel 1 exit /b 1 |
|||
echo. |
|||
echo.Build finished. The message catalogs are in %BUILDDIR%/locale. |
|||
goto end |
|||
) |
|||
|
|||
if "%1" == "changes" ( |
|||
%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes |
|||
if errorlevel 1 exit /b 1 |
|||
echo. |
|||
echo.The overview file is in %BUILDDIR%/changes. |
|||
goto end |
|||
) |
|||
|
|||
if "%1" == "linkcheck" ( |
|||
%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck |
|||
if errorlevel 1 exit /b 1 |
|||
echo. |
|||
echo.Link check complete; look for any errors in the above output ^ |
|||
or in %BUILDDIR%/linkcheck/output.txt. |
|||
goto end |
|||
) |
|||
|
|||
if "%1" == "doctest" ( |
|||
%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest |
|||
if errorlevel 1 exit /b 1 |
|||
echo. |
|||
echo.Testing of doctests in the sources finished, look at the ^ |
|||
results in %BUILDDIR%/doctest/output.txt. |
|||
goto end |
|||
) |
|||
|
|||
if "%1" == "xml" ( |
|||
%SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml |
|||
if errorlevel 1 exit /b 1 |
|||
echo. |
|||
echo.Build finished. The XML files are in %BUILDDIR%/xml. |
|||
goto end |
|||
) |
|||
|
|||
if "%1" == "pseudoxml" ( |
|||
%SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml |
|||
if errorlevel 1 exit /b 1 |
|||
echo. |
|||
echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml. |
|||
goto end |
|||
) |
|||
|
|||
:end |
|||
@ -0,0 +1,56 @@ |
|||
|
|||
.. _async: |
|||
|
|||
:c:type:`uv_async_t` --- Async handle |
|||
===================================== |
|||
|
|||
Async handles allow the user to "wakeup" the event loop and get a callback |
|||
called from another thread. |
|||
|
|||
|
|||
Data types |
|||
---------- |
|||
|
|||
.. c:type:: uv_async_t |
|||
|
|||
Async handle type. |
|||
|
|||
.. c:type:: void (*uv_async_cb)(uv_async_t* handle) |
|||
|
|||
Type definition for callback passed to :c:func:`uv_async_init`. |
|||
|
|||
|
|||
Public members |
|||
^^^^^^^^^^^^^^ |
|||
|
|||
N/A |
|||
|
|||
.. seealso:: The :c:type:`uv_handle_t` members also apply. |
|||
|
|||
|
|||
API |
|||
--- |
|||
|
|||
.. c:function:: int uv_async_init(uv_loop_t* loop, uv_async_t* async, uv_async_cb async_cb) |
|||
|
|||
Initialize the handle. A NULL callback is allowed. |
|||
|
|||
.. note:: |
|||
Unlike other handle initialization functions, it immediately starts the handle. |
|||
|
|||
.. c:function:: int uv_async_send(uv_async_t* async) |
|||
|
|||
Wakeup the event loop and call the async handle's callback. |
|||
|
|||
.. note:: |
|||
It's safe to call this function from any thread. The callback will be called on the |
|||
loop thread. |
|||
|
|||
.. warning:: |
|||
libuv will coalesce calls to :c:func:`uv_async_send`, that is, not every call to it will |
|||
yield an execution of the callback, the only guarantee is that it will be called at least |
|||
once. Thus, calling this function may not wakeup the event loop if it was already called |
|||
previously within a short period of time. |
|||
|
|||
.. seealso:: |
|||
The :c:type:`uv_handle_t` API functions also apply. |
|||
@ -0,0 +1,46 @@ |
|||
|
|||
.. _check: |
|||
|
|||
:c:type:`uv_check_t` --- Check handle |
|||
===================================== |
|||
|
|||
Check handles will run the given callback once per loop iteration, right |
|||
after polling for i/o. |
|||
|
|||
|
|||
Data types |
|||
---------- |
|||
|
|||
.. c:type:: uv_check_t |
|||
|
|||
Check handle type. |
|||
|
|||
.. c:type:: void (*uv_check_cb)(uv_check_t* handle) |
|||
|
|||
Type definition for callback passed to :c:func:`uv_check_start`. |
|||
|
|||
|
|||
Public members |
|||
^^^^^^^^^^^^^^ |
|||
|
|||
N/A |
|||
|
|||
.. seealso:: The :c:type:`uv_handle_t` members also apply. |
|||
|
|||
|
|||
API |
|||
--- |
|||
|
|||
.. c:function:: int uv_check_init(uv_loop_t*, uv_check_t* check) |
|||
|
|||
Initialize the handle. |
|||
|
|||
.. c:function:: int uv_check_start(uv_check_t* check, uv_check_cb cb) |
|||
|
|||
Start the handle with the given callback. |
|||
|
|||
.. c:function:: int uv_check_stop(uv_check_t* check) |
|||
|
|||
Stop the handle, the callback will no longer be called. |
|||
|
|||
.. seealso:: The :c:type:`uv_handle_t` API functions also apply. |
|||
@ -0,0 +1,348 @@ |
|||
# -*- coding: utf-8 -*- |
|||
# |
|||
# libuv API documentation documentation build configuration file, created by |
|||
# sphinx-quickstart on Sun Jul 27 11:47:51 2014. |
|||
# |
|||
# This file is execfile()d with the current directory set to its |
|||
# containing dir. |
|||
# |
|||
# Note that not all possible configuration values are present in this |
|||
# autogenerated file. |
|||
# |
|||
# All configuration values have a default; values that are commented out |
|||
# serve to show the default. |
|||
|
|||
import os |
|||
import re |
|||
import sys |
|||
|
|||
|
|||
def get_libuv_version(): |
|||
with open('../../include/uv-version.h') as f: |
|||
data = f.read() |
|||
try: |
|||
m = re.search(r"""^#define UV_VERSION_MAJOR (\d)$""", data, re.MULTILINE) |
|||
major = int(m.group(1)) |
|||
m = re.search(r"""^#define UV_VERSION_MINOR (\d)$""", data, re.MULTILINE) |
|||
minor = int(m.group(1)) |
|||
m = re.search(r"""^#define UV_VERSION_PATCH (\d)$""", data, re.MULTILINE) |
|||
patch = int(m.group(1)) |
|||
m = re.search(r"""^#define UV_VERSION_IS_RELEASE (\d)$""", data, re.MULTILINE) |
|||
is_release = int(m.group(1)) |
|||
m = re.search(r"""^#define UV_VERSION_SUFFIX \"(\w*)\"$""", data, re.MULTILINE) |
|||
suffix = m.group(1) |
|||
return '%d.%d.%d%s' % (major, minor, patch, '-%s' % suffix if not is_release else '') |
|||
except Exception: |
|||
return 'unknown' |
|||
|
|||
# If extensions (or modules to document with autodoc) are in another directory, |
|||
# add these directories to sys.path here. If the directory is relative to the |
|||
# documentation root, use os.path.abspath to make it absolute, like shown here. |
|||
#sys.path.insert(0, os.path.abspath('.')) |
|||
|
|||
# -- General configuration ------------------------------------------------ |
|||
|
|||
# If your documentation needs a minimal Sphinx version, state it here. |
|||
#needs_sphinx = '1.0' |
|||
|
|||
# Add any Sphinx extension module names here, as strings. They can be |
|||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom |
|||
# ones. |
|||
extensions = [] |
|||
|
|||
# Add any paths that contain templates here, relative to this directory. |
|||
templates_path = ['templates'] |
|||
|
|||
# The suffix of source filenames. |
|||
source_suffix = '.rst' |
|||
|
|||
# The encoding of source files. |
|||
#source_encoding = 'utf-8-sig' |
|||
|
|||
# The master toctree document. |
|||
master_doc = 'index' |
|||
|
|||
# General information about the project. |
|||
project = u'libuv API documentation' |
|||
copyright = u'libuv contributors' |
|||
|
|||
# The version info for the project you're documenting, acts as replacement for |
|||
# |version| and |release|, also used in various other places throughout the |
|||
# built documents. |
|||
# |
|||
# The short X.Y version. |
|||
version = get_libuv_version() |
|||
# The full version, including alpha/beta/rc tags. |
|||
release = version |
|||
|
|||
# The language for content autogenerated by Sphinx. Refer to documentation |
|||
# for a list of supported languages. |
|||
#language = None |
|||
|
|||
# There are two options for replacing |today|: either, you set today to some |
|||
# non-false value, then it is used: |
|||
#today = '' |
|||
# Else, today_fmt is used as the format for a strftime call. |
|||
#today_fmt = '%B %d, %Y' |
|||
|
|||
# List of patterns, relative to source directory, that match files and |
|||
# directories to ignore when looking for source files. |
|||
exclude_patterns = [] |
|||
|
|||
# The reST default role (used for this markup: `text`) to use for all |
|||
# documents. |
|||
#default_role = None |
|||
|
|||
# If true, '()' will be appended to :func: etc. cross-reference text. |
|||
#add_function_parentheses = True |
|||
|
|||
# If true, the current module name will be prepended to all description |
|||
# unit titles (such as .. function::). |
|||
#add_module_names = True |
|||
|
|||
# If true, sectionauthor and moduleauthor directives will be shown in the |
|||
# output. They are ignored by default. |
|||
#show_authors = False |
|||
|
|||
# The name of the Pygments (syntax highlighting) style to use. |
|||
pygments_style = 'sphinx' |
|||
|
|||
# A list of ignored prefixes for module index sorting. |
|||
#modindex_common_prefix = [] |
|||
|
|||
# If true, keep warnings as "system message" paragraphs in the built documents. |
|||
#keep_warnings = False |
|||
|
|||
|
|||
# -- Options for HTML output ---------------------------------------------- |
|||
|
|||
# The theme to use for HTML and HTML Help pages. See the documentation for |
|||
# a list of builtin themes. |
|||
html_theme = 'nature' |
|||
|
|||
# Theme options are theme-specific and customize the look and feel of a theme |
|||
# further. For a list of options available for each theme, see the |
|||
# documentation. |
|||
#html_theme_options = {} |
|||
|
|||
# Add any paths that contain custom themes here, relative to this directory. |
|||
#html_theme_path = [] |
|||
|
|||
# The name for this set of Sphinx documents. If None, it defaults to |
|||
# "<project> v<release> documentation". |
|||
html_title = 'libuv API documentation' |
|||
|
|||
# A shorter title for the navigation bar. Default is the same as html_title. |
|||
html_short_title = 'libuv %s API documentation' % version |
|||
|
|||
# The name of an image file (relative to this directory) to place at the top |
|||
# of the sidebar. |
|||
html_logo = 'static/logo.png' |
|||
|
|||
# The name of an image file (within the static path) to use as favicon of the |
|||
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 |
|||
# pixels large. |
|||
html_favicon = 'static/favicon.ico' |
|||
|
|||
# Add any paths that contain custom static files (such as style sheets) here, |
|||
# relative to this directory. They are copied after the builtin static files, |
|||
# so a file named "default.css" will overwrite the builtin "default.css". |
|||
html_static_path = ['static'] |
|||
|
|||
# Add any extra paths that contain custom files (such as robots.txt or |
|||
# .htaccess) here, relative to this directory. These files are copied |
|||
# directly to the root of the documentation. |
|||
#html_extra_path = [] |
|||
|
|||
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, |
|||
# using the given strftime format. |
|||
#html_last_updated_fmt = '%b %d, %Y' |
|||
|
|||
# If true, SmartyPants will be used to convert quotes and dashes to |
|||
# typographically correct entities. |
|||
#html_use_smartypants = True |
|||
|
|||
# Custom sidebar templates, maps document names to template names. |
|||
#html_sidebars = {} |
|||
|
|||
# Additional templates that should be rendered to pages, maps page names to |
|||
# template names. |
|||
#html_additional_pages = {} |
|||
|
|||
# If false, no module index is generated. |
|||
#html_domain_indices = True |
|||
|
|||
# If false, no index is generated. |
|||
#html_use_index = True |
|||
|
|||
# If true, the index is split into individual pages for each letter. |
|||
#html_split_index = False |
|||
|
|||
# If true, links to the reST sources are added to the pages. |
|||
#html_show_sourcelink = True |
|||
|
|||
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. |
|||
#html_show_sphinx = True |
|||
|
|||
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. |
|||
#html_show_copyright = True |
|||
|
|||
# If true, an OpenSearch description file will be output, and all pages will |
|||
# contain a <link> tag referring to it. The value of this option must be the |
|||
# base URL from which the finished HTML is served. |
|||
#html_use_opensearch = '' |
|||
|
|||
# This is the file name suffix for HTML files (e.g. ".xhtml"). |
|||
#html_file_suffix = None |
|||
|
|||
# Output file base name for HTML help builder. |
|||
htmlhelp_basename = 'libuv' |
|||
|
|||
|
|||
# -- Options for LaTeX output --------------------------------------------- |
|||
|
|||
latex_elements = { |
|||
# The paper size ('letterpaper' or 'a4paper'). |
|||
#'papersize': 'letterpaper', |
|||
|
|||
# The font size ('10pt', '11pt' or '12pt'). |
|||
#'pointsize': '10pt', |
|||
|
|||
# Additional stuff for the LaTeX preamble. |
|||
#'preamble': '', |
|||
} |
|||
|
|||
# Grouping the document tree into LaTeX files. List of tuples |
|||
# (source start file, target name, title, |
|||
# author, documentclass [howto, manual, or own class]). |
|||
latex_documents = [ |
|||
('index', 'libuv.tex', u'libuv API documentation', |
|||
u'libuv contributors', 'manual'), |
|||
] |
|||
|
|||
# The name of an image file (relative to this directory) to place at the top of |
|||
# the title page. |
|||
#latex_logo = None |
|||
|
|||
# For "manual" documents, if this is true, then toplevel headings are parts, |
|||
# not chapters. |
|||
#latex_use_parts = False |
|||
|
|||
# If true, show page references after internal links. |
|||
#latex_show_pagerefs = False |
|||
|
|||
# If true, show URL addresses after external links. |
|||
#latex_show_urls = False |
|||
|
|||
# Documents to append as an appendix to all manuals. |
|||
#latex_appendices = [] |
|||
|
|||
# If false, no module index is generated. |
|||
#latex_domain_indices = True |
|||
|
|||
|
|||
# -- Options for manual page output --------------------------------------- |
|||
|
|||
# One entry per manual page. List of tuples |
|||
# (source start file, name, description, authors, manual section). |
|||
man_pages = [ |
|||
('index', 'libuv', u'libuv API documentation', |
|||
[u'libuv contributors'], 1) |
|||
] |
|||
|
|||
# If true, show URL addresses after external links. |
|||
#man_show_urls = False |
|||
|
|||
|
|||
# -- Options for Texinfo output ------------------------------------------- |
|||
|
|||
# Grouping the document tree into Texinfo files. List of tuples |
|||
# (source start file, target name, title, author, |
|||
# dir menu entry, description, category) |
|||
texinfo_documents = [ |
|||
('index', 'libuv', u'libuv API documentation', |
|||
u'libuv contributors', 'libuv', 'Cross-platform asychronous I/O', |
|||
'Miscellaneous'), |
|||
] |
|||
|
|||
# Documents to append as an appendix to all manuals. |
|||
#texinfo_appendices = [] |
|||
|
|||
# If false, no module index is generated. |
|||
#texinfo_domain_indices = True |
|||
|
|||
# How to display URL addresses: 'footnote', 'no', or 'inline'. |
|||
#texinfo_show_urls = 'footnote' |
|||
|
|||
# If true, do not generate a @detailmenu in the "Top" node's menu. |
|||
#texinfo_no_detailmenu = False |
|||
|
|||
|
|||
# -- Options for Epub output ---------------------------------------------- |
|||
|
|||
# Bibliographic Dublin Core info. |
|||
epub_title = u'libuv API documentation' |
|||
epub_author = u'libuv contributors' |
|||
epub_publisher = u'libuv contributors' |
|||
epub_copyright = u'2014, libuv contributors' |
|||
|
|||
# The basename for the epub file. It defaults to the project name. |
|||
epub_basename = u'libuv' |
|||
|
|||
# The HTML theme for the epub output. Since the default themes are not optimized |
|||
# for small screen space, using the same theme for HTML and epub output is |
|||
# usually not wise. This defaults to 'epub', a theme designed to save visual |
|||
# space. |
|||
#epub_theme = 'epub' |
|||
|
|||
# The language of the text. It defaults to the language option |
|||
# or en if the language is not set. |
|||
#epub_language = '' |
|||
|
|||
# The scheme of the identifier. Typical schemes are ISBN or URL. |
|||
#epub_scheme = '' |
|||
|
|||
# The unique identifier of the text. This can be a ISBN number |
|||
# or the project homepage. |
|||
#epub_identifier = '' |
|||
|
|||
# A unique identification for the text. |
|||
#epub_uid = '' |
|||
|
|||
# A tuple containing the cover image and cover page html template filenames. |
|||
#epub_cover = () |
|||
|
|||
# A sequence of (type, uri, title) tuples for the guide element of content.opf. |
|||
#epub_guide = () |
|||
|
|||
# HTML files that should be inserted before the pages created by sphinx. |
|||
# The format is a list of tuples containing the path and title. |
|||
#epub_pre_files = [] |
|||
|
|||
# HTML files shat should be inserted after the pages created by sphinx. |
|||
# The format is a list of tuples containing the path and title. |
|||
#epub_post_files = [] |
|||
|
|||
# A list of files that should not be packed into the epub file. |
|||
epub_exclude_files = ['search.html'] |
|||
|
|||
# The depth of the table of contents in toc.ncx. |
|||
#epub_tocdepth = 3 |
|||
|
|||
# Allow duplicate toc entries. |
|||
#epub_tocdup = True |
|||
|
|||
# Choose between 'default' and 'includehidden'. |
|||
#epub_tocscope = 'default' |
|||
|
|||
# Fix unsupported image types using the PIL. |
|||
#epub_fix_images = False |
|||
|
|||
# Scale large images. |
|||
#epub_max_image_width = 0 |
|||
|
|||
# How to display URL addresses: 'footnote', 'no', or 'inline'. |
|||
#epub_show_urls = 'inline' |
|||
|
|||
# If false, no index is generated. |
|||
#epub_use_index = True |
|||
@ -0,0 +1,137 @@ |
|||
|
|||
.. _design: |
|||
|
|||
Design overview |
|||
=============== |
|||
|
|||
libuv is cross-platform support library which was originally written for NodeJS. It's designed |
|||
around the event-driven asynchronous I/O model. |
|||
|
|||
The library provides much more than simply abstraction over different I/O polling mechanisms: |
|||
'handles' and 'streams' provde a high level abstraction for sockets and other entities; |
|||
cross-platform file I/O and threading functionality is also provided, amongst other things. |
|||
|
|||
Here is a diagram illustrating the different parts that compose libuv and what subsystem they |
|||
relate to: |
|||
|
|||
.. image:: static/architecture.png |
|||
:scale: 75% |
|||
:align: center |
|||
|
|||
|
|||
Handles and requests |
|||
^^^^^^^^^^^^^^^^^^^^ |
|||
|
|||
libuv provides users with 2 abstractions to work with, in combination with the event loop: |
|||
handles and requests. |
|||
|
|||
Handles represent long-lived objects capable of performing certain operations while active. Some |
|||
examples: a prepare handle gets its callback called once every loop iteration when active, and |
|||
a TCP server handle get its connection callback called every time there is a new connection. |
|||
|
|||
Requests represent (typically) short-lived operations. These operations can be performed over a |
|||
handle: write requests are used to write data on a handle; or standalone: getaddrinfo requests |
|||
don't need a handle they run directly on the loop. |
|||
|
|||
|
|||
The I/O loop |
|||
^^^^^^^^^^^^ |
|||
|
|||
The I/O (or event) loop is the central part of libuv. It establishes the content for all I/O |
|||
operations, and it's meant to be tied to a single thread. One can run multiple event loops |
|||
as long as each runs in a different thread. The libuv event loop (or any other API involving |
|||
the loop or handles, for that matter) **is not thread-safe** except stated otherwise. |
|||
|
|||
The event loop follows the rather usual single threaded asynchronous I/O approah: all (network) |
|||
I/O is performed on non-blocking sockets which are polled using the best mechanism available |
|||
on the given platform: epoll on Linux, kqueue on OSX and other BSDs, event ports on SunOS and IOCP |
|||
on Windows. As part of a loop iteration the loop will block waiting for I/O activity on sockets |
|||
which have been added to the poller and callbacks will be fired indicating socket conditions |
|||
(readable, writable hangup) so handles can read, write or perform the desired I/O operation. |
|||
|
|||
In order to better understand how the event loop operates, the following diagram illustrates all |
|||
stages of a loop iteration: |
|||
|
|||
.. image:: static/loop_iteration.png |
|||
:scale: 75% |
|||
:align: center |
|||
|
|||
|
|||
#. The loop concept of 'now' is updated. The event loop caches the current time at the start of |
|||
the event loop tick in order to reduce the number of time-related system calls. |
|||
|
|||
#. If the loop is *alive* an iteration is started, otherwise the loop will exit immediately. So, |
|||
when is a loop considered to be *alive*? If a loop has active and ref'd handles, active |
|||
requests or closing handles it's considered to be *alive*. |
|||
|
|||
#. Due timers are run. All active timers scheduled for a time before the loop's concept of *now* |
|||
get their callbacks called. |
|||
|
|||
#. Pending callbacks are called. All I/O callbacks are called right after polling for I/O, for the |
|||
most part. There are cases, however, in which calling such a callback is deferred for the next |
|||
loop iteration. If the previous iteration deferred any I/O callback it will be run at this point. |
|||
|
|||
#. Idle handle callbacks are called. Despite the unfortunate name, idle handles are run on every |
|||
loop iteration, if they are active. |
|||
|
|||
#. Prepare handle callbacks are called. Prepare handles get their callbacks called right before |
|||
the loop will block for I/O. |
|||
|
|||
#. Poll timeout is calculated. Before blocking for I/O the loop calculates for how long it should |
|||
block. These are the rules when calculating the timeout: |
|||
|
|||
* If the loop was run with the ``UV_RUN_NOWAIT`` flag, the timeout is 0. |
|||
* If the loop is going to be stopped (:c:func:`uv_stop` was called), the timeout is 0. |
|||
* If there are no active handles or requests, the timeout is 0. |
|||
* If there are any idle handles active, the timeout is 0. |
|||
* If there are any handles pending to be closed, the timeout is 0. |
|||
* If none of the above cases was matched, the timeout of the closest timer is taken, or |
|||
if there are no active timers, infinity. |
|||
|
|||
#. The loop blocks for I/O. At this point the loop will block for I/O for the timeout calculated |
|||
on the previous step. All I/O related handles that were monitoring a given file descriptor |
|||
for a read or write operation get their callbacks called at this point. |
|||
|
|||
#. Check handle callbacks are called. Check handles get their callbacks called right after the |
|||
loop has blocked for I/O. Check handles are essentially the counterpart of prepare handles. |
|||
|
|||
#. Close callbacks are called. If a handle was closed by calling :c:func:`uv_close` it will |
|||
get the close callback called. |
|||
|
|||
#. Special case in case the loop was run with ``UV_RUN_ONCE``, as it implies forward progress. |
|||
It's possible that no I/O callbacks were fired after blocking for I/O, but some time has passed |
|||
so there might be timers which are due, those timers get their callbacks called. |
|||
|
|||
#. Iteration ends. If the loop was run with ``UV_RUN_NOWAIT`` or ``UV_RUN_ONCE`` modes the |
|||
iteration is ended and :c:func:`uv_run` will return. If the loop was run with ``UV_RUN_DEFAULT`` |
|||
it will contionue from the start if it's asill *alive*, otherwise it will also end. |
|||
|
|||
|
|||
.. important:: |
|||
libuv uses a thread pool to make asynchronous file I/O operations possible, but |
|||
network I/O is **always** performed in a single thread, each loop's thread. |
|||
|
|||
.. note:: |
|||
While the polling mechanism is different, libuv makes the execution model consistent |
|||
Unix systems and Windows. |
|||
|
|||
|
|||
File I/O |
|||
^^^^^^^^ |
|||
|
|||
Unlike network I/O, there are no platform-specific file I/O primitives libuv could rely on, |
|||
so the current approach is to run blocking file I/O operations in a thread pool. |
|||
|
|||
For a thorough explanation of the cross-platform file I/O landscape, checkout |
|||
`this post <http://blog.libtorrent.org/2012/10/asynchronous-disk-io/>`_. |
|||
|
|||
libuv currently uses a global thread pool on which all loops can queue work on. 3 types of |
|||
operations are currently run on this pool: |
|||
|
|||
* Filesystem operations |
|||
* DNS functions (getaddrinfo and getnameinfo) |
|||
* User specified code via :c:func:`uv_queue_work` |
|||
|
|||
.. warning:: |
|||
See the :c:ref:`threadpool` section for more details, but keep in mind the thread pool size |
|||
is quite limited. |
|||
@ -0,0 +1,44 @@ |
|||
|
|||
.. _dll: |
|||
|
|||
Shared library handling |
|||
======================= |
|||
|
|||
libuv prodives cross platform utilities for loading shared libraries and |
|||
retrieving symbols from them, using the following API. |
|||
|
|||
|
|||
Data types |
|||
---------- |
|||
|
|||
.. c:type:: uv_lib_t |
|||
|
|||
Shared library data type. |
|||
|
|||
|
|||
Public members |
|||
^^^^^^^^^^^^^^ |
|||
|
|||
N/A |
|||
|
|||
|
|||
API |
|||
--- |
|||
|
|||
.. c:function:: int uv_dlopen(const char* filename, uv_lib_t* lib) |
|||
|
|||
Opens a shared library. The filename is in utf-8. Returns 0 on success and |
|||
-1 on error. Call :c:func:`uv_dlerror` to get the error message. |
|||
|
|||
.. c:function:: void uv_dlclose(uv_lib_t* lib) |
|||
|
|||
Close the shared library. |
|||
|
|||
.. c:function:: uv_dlsym(uv_lib_t* lib, const char* name, void** ptr) |
|||
|
|||
Retrieves a data pointer from a dynamic library. It is legal for a symbol |
|||
to map to NULL. Returns 0 on success and -1 if the symbol was not found. |
|||
|
|||
.. c:function:: const char* uv_dlerror(const uv_lib_t* lib) |
|||
|
|||
Returns the last uv_dlopen() or uv_dlsym() error message. |
|||
@ -0,0 +1,83 @@ |
|||
|
|||
.. _dns: |
|||
|
|||
DNS utility functions |
|||
===================== |
|||
|
|||
libuv provides asynchronous variants of `getaddrinfo` and `getnameinfo`. |
|||
|
|||
|
|||
Data types |
|||
---------- |
|||
|
|||
.. c:type:: uv_getaddrinfo_t |
|||
|
|||
`getaddrinfo` request type. |
|||
|
|||
.. c:type:: void (*uv_getaddrinfo_cb)(uv_getaddrinfo_t* req, int status, struct addrinfo* res) |
|||
|
|||
Callback which will be called with the getaddrinfo request result once |
|||
complete. In case it was cancelled, `status` will have a value of |
|||
``UV_ECANCELED``. |
|||
|
|||
.. c:type:: uv_getnameinfo_t |
|||
|
|||
`getnameinfo` request type. |
|||
|
|||
.. c:type:: void (*uv_getnameinfo_cb)(uv_getnameinfo_t* req, int status, const char* hostname, const char* service) |
|||
|
|||
Callback which will be called with the getnameinfo request result once |
|||
complete. In case it was cancelled, `status` will have a value of |
|||
``UV_ECANCELED``. |
|||
|
|||
|
|||
Public members |
|||
^^^^^^^^^^^^^^ |
|||
|
|||
.. c:member:: uv_loop_t* uv_getaddrinfo_t.loop |
|||
|
|||
Loop that started this getaddrinfo request and where completion will be |
|||
reported. Readonly. |
|||
|
|||
.. c:member:: uv_loop_t* uv_getnameinfo_t.loop |
|||
|
|||
Loop that started this getnameinfo request and where completion will be |
|||
reported. Readonly. |
|||
|
|||
.. seealso:: The :c:type:`uv_req_t` members also apply. |
|||
|
|||
|
|||
API |
|||
--- |
|||
|
|||
.. c:function:: int uv_getaddrinfo(uv_loop_t* loop, uv_getaddrinfo_t* req, uv_getaddrinfo_cb getaddrinfo_cb, const char* node, const char* service, const struct addrinfo* hints) |
|||
|
|||
Asynchronous ``getaddrinfo(3)``. |
|||
|
|||
Either node or service may be NULL but not both. |
|||
|
|||
`hints` is a pointer to a struct addrinfo with additional address type |
|||
constraints, or NULL. Consult `man -s 3 getaddrinfo` for more details. |
|||
|
|||
Returns 0 on success or an error code < 0 on failure. If successful, the |
|||
callback will get called sometime in the future with the lookup result, |
|||
which is either: |
|||
|
|||
* status == 0, the res argument points to a valid `struct addrinfo`, or |
|||
* status < 0, the res argument is NULL. See the UV_EAI_* constants. |
|||
|
|||
Call :c:func:`uv_freeaddrinfo` to free the addrinfo structure. |
|||
|
|||
.. c:function:: void uv_freeaddrinfo(struct addrinfo* ai) |
|||
|
|||
Free the struct addrinfo. Passing NULL is allowed and is a no-op. |
|||
|
|||
.. c:function:: int uv_getnameinfo(uv_loop_t* loop, uv_getnameinfo_t* req, uv_getnameinfo_cb getnameinfo_cb, const struct sockaddr* addr, int flags) |
|||
|
|||
Asynchronous ``getnameinfo(3)``. |
|||
|
|||
Returns 0 on success or an error code < 0 on failure. If successful, the |
|||
callback will get called sometime in the future with the lookup result. |
|||
Consult `man -s 3 getnameinfo` for more details. |
|||
|
|||
.. seealso:: The :c:type:`uv_req_t` API functions also apply. |
|||
@ -0,0 +1,329 @@ |
|||
|
|||
.. _errors: |
|||
|
|||
Error handling |
|||
============== |
|||
|
|||
In libuv errors are negative numbered constants. As a rule of thumb, whenever |
|||
there is a status parameter, or an API functions returns an integer, a negative |
|||
number will imply an error. |
|||
|
|||
.. note:: |
|||
Implementation detail: on Unix error codes are the negated `errno` (or `-errno`), while on |
|||
Windows they are defined by libuv to arbitrary negative numbers. |
|||
|
|||
|
|||
Error constants |
|||
--------------- |
|||
|
|||
.. c:macro:: UV_E2BIG |
|||
|
|||
argument list too long |
|||
|
|||
.. c:macro:: UV_EACCES |
|||
|
|||
permission denied |
|||
|
|||
.. c:macro:: UV_EADDRINUSE |
|||
|
|||
address already in use |
|||
|
|||
.. c:macro:: UV_EADDRNOTAVAIL |
|||
|
|||
address not available |
|||
|
|||
.. c:macro:: UV_EAFNOSUPPORT |
|||
|
|||
address family not supported |
|||
|
|||
.. c:macro:: UV_EAGAIN |
|||
|
|||
resource temporarily unavailable |
|||
|
|||
.. c:macro:: UV_EAI_ADDRFAMILY |
|||
|
|||
address family not supported |
|||
|
|||
.. c:macro:: UV_EAI_AGAIN |
|||
|
|||
temporary failure |
|||
|
|||
.. c:macro:: UV_EAI_BADFLAGS |
|||
|
|||
bad ai_flags value |
|||
|
|||
.. c:macro:: UV_EAI_BADHINTS |
|||
|
|||
invalid value for hints |
|||
|
|||
.. c:macro:: UV_EAI_CANCELED |
|||
|
|||
request canceled |
|||
|
|||
.. c:macro:: UV_EAI_FAIL |
|||
|
|||
permanent failure |
|||
|
|||
.. c:macro:: UV_EAI_FAMILY |
|||
|
|||
ai_family not supported |
|||
|
|||
.. c:macro:: UV_EAI_MEMORY |
|||
|
|||
out of memory |
|||
|
|||
.. c:macro:: UV_EAI_NODATA |
|||
|
|||
no address |
|||
|
|||
.. c:macro:: UV_EAI_NONAME |
|||
|
|||
unknown node or service |
|||
|
|||
.. c:macro:: UV_EAI_OVERFLOW |
|||
|
|||
argument buffer overflow |
|||
|
|||
.. c:macro:: UV_EAI_PROTOCOL |
|||
|
|||
resolved protocol is unknown |
|||
|
|||
.. c:macro:: UV_EAI_SERVICE |
|||
|
|||
service not available for socket type |
|||
|
|||
.. c:macro:: UV_EAI_SOCKTYPE |
|||
|
|||
socket type not supported |
|||
|
|||
.. c:macro:: UV_EALREADY |
|||
|
|||
connection already in progress |
|||
|
|||
.. c:macro:: UV_EBADF |
|||
|
|||
bad file descriptor |
|||
|
|||
.. c:macro:: UV_EBUSY |
|||
|
|||
resource busy or locked |
|||
|
|||
.. c:macro:: UV_ECANCELED |
|||
|
|||
operation canceled |
|||
|
|||
.. c:macro:: UV_ECHARSET |
|||
|
|||
invalid Unicode character |
|||
|
|||
.. c:macro:: UV_ECONNABORTED |
|||
|
|||
software caused connection abort |
|||
|
|||
.. c:macro:: UV_ECONNREFUSED |
|||
|
|||
connection refused |
|||
|
|||
.. c:macro:: UV_ECONNRESET |
|||
|
|||
connection reset by peer |
|||
|
|||
.. c:macro:: UV_EDESTADDRREQ |
|||
|
|||
destination address required |
|||
|
|||
.. c:macro:: UV_EEXIST |
|||
|
|||
file already exists |
|||
|
|||
.. c:macro:: UV_EFAULT |
|||
|
|||
bad address in system call argument |
|||
|
|||
.. c:macro:: UV_EFBIG |
|||
|
|||
file too large |
|||
|
|||
.. c:macro:: UV_EHOSTUNREACH |
|||
|
|||
host is unreachable |
|||
|
|||
.. c:macro:: UV_EINTR |
|||
|
|||
interrupted system call |
|||
|
|||
.. c:macro:: UV_EINVAL |
|||
|
|||
invalid argument |
|||
|
|||
.. c:macro:: UV_EIO |
|||
|
|||
i/o error |
|||
|
|||
.. c:macro:: UV_EISCONN |
|||
|
|||
socket is already connected |
|||
|
|||
.. c:macro:: UV_EISDIR |
|||
|
|||
illegal operation on a directory |
|||
|
|||
.. c:macro:: UV_ELOOP |
|||
|
|||
too many symbolic links encountered |
|||
|
|||
.. c:macro:: UV_EMFILE |
|||
|
|||
too many open files |
|||
|
|||
.. c:macro:: UV_EMSGSIZE |
|||
|
|||
message too long |
|||
|
|||
.. c:macro:: UV_ENAMETOOLONG |
|||
|
|||
name too long |
|||
|
|||
.. c:macro:: UV_ENETDOWN |
|||
|
|||
network is down |
|||
|
|||
.. c:macro:: UV_ENETUNREACH |
|||
|
|||
network is unreachable |
|||
|
|||
.. c:macro:: UV_ENFILE |
|||
|
|||
file table overflow |
|||
|
|||
.. c:macro:: UV_ENOBUFS |
|||
|
|||
no buffer space available |
|||
|
|||
.. c:macro:: UV_ENODEV |
|||
|
|||
no such device |
|||
|
|||
.. c:macro:: UV_ENOENT |
|||
|
|||
no such file or directory |
|||
|
|||
.. c:macro:: UV_ENOMEM |
|||
|
|||
not enough memory |
|||
|
|||
.. c:macro:: UV_ENONET |
|||
|
|||
machine is not on the network |
|||
|
|||
.. c:macro:: UV_ENOPROTOOPT |
|||
|
|||
protocol not available |
|||
|
|||
.. c:macro:: UV_ENOSPC |
|||
|
|||
no space left on device |
|||
|
|||
.. c:macro:: UV_ENOSYS |
|||
|
|||
function not implemented |
|||
|
|||
.. c:macro:: UV_ENOTCONN |
|||
|
|||
socket is not connected |
|||
|
|||
.. c:macro:: UV_ENOTDIR |
|||
|
|||
not a directory |
|||
|
|||
.. c:macro:: UV_ENOTEMPTY |
|||
|
|||
directory not empty |
|||
|
|||
.. c:macro:: UV_ENOTSOCK |
|||
|
|||
socket operation on non-socket |
|||
|
|||
.. c:macro:: UV_ENOTSUP |
|||
|
|||
operation not supported on socket |
|||
|
|||
.. c:macro:: UV_EPERM |
|||
|
|||
operation not permitted |
|||
|
|||
.. c:macro:: UV_EPIPE |
|||
|
|||
broken pipe |
|||
|
|||
.. c:macro:: UV_EPROTO |
|||
|
|||
protocol error |
|||
|
|||
.. c:macro:: UV_EPROTONOSUPPORT |
|||
|
|||
protocol not supported |
|||
|
|||
.. c:macro:: UV_EPROTOTYPE |
|||
|
|||
protocol wrong type for socket |
|||
|
|||
.. c:macro:: UV_ERANGE |
|||
|
|||
result too large |
|||
|
|||
.. c:macro:: UV_EROFS |
|||
|
|||
read-only file system |
|||
|
|||
.. c:macro:: UV_ESHUTDOWN |
|||
|
|||
cannot send after transport endpoint shutdown |
|||
|
|||
.. c:macro:: UV_ESPIPE |
|||
|
|||
invalid seek |
|||
|
|||
.. c:macro:: UV_ESRCH |
|||
|
|||
no such process |
|||
|
|||
.. c:macro:: UV_ETIMEDOUT |
|||
|
|||
connection timed out |
|||
|
|||
.. c:macro:: UV_ETXTBSY |
|||
|
|||
text file is busy |
|||
|
|||
.. c:macro:: UV_EXDEV |
|||
|
|||
cross-device link not permitted |
|||
|
|||
.. c:macro:: UV_UNKNOWN |
|||
|
|||
unknown error |
|||
|
|||
.. c:macro:: UV_EOF |
|||
|
|||
end of file |
|||
|
|||
.. c:macro:: UV_ENXIO |
|||
|
|||
no such device or address |
|||
|
|||
.. c:macro:: UV_EMLINK |
|||
|
|||
too many links |
|||
|
|||
|
|||
API |
|||
--- |
|||
|
|||
.. c:function:: const char* uv_strerror(int err) |
|||
|
|||
Returns the error message for the given error code. |
|||
|
|||
.. c:function:: const char* uv_err_name(int err) |
|||
|
|||
Returns the error name for the given error code. |
|||
@ -0,0 +1,259 @@ |
|||
|
|||
.. _fs: |
|||
|
|||
Filesystem operations |
|||
===================== |
|||
|
|||
libuv provides a wide variety of cross-platform sync and async filesystem |
|||
operations. All functions defined in this document take a callback, which is |
|||
allowed to be NULL. If the callback is NULL the request is completed synchronously, |
|||
otherwise it will be performed asynchronously. |
|||
|
|||
All file operations are run on the threadpool, see :ref:`threadpool` for information |
|||
on the threadpool size. |
|||
|
|||
|
|||
Data types |
|||
---------- |
|||
|
|||
.. c:type:: uv_fs_t |
|||
|
|||
Filesystem request type. |
|||
|
|||
.. c:type:: uv_stat_t |
|||
|
|||
Portable equivalent of `struct stat`. |
|||
|
|||
:: |
|||
|
|||
typedef struct { |
|||
uint64_t st_dev; |
|||
uint64_t st_mode; |
|||
uint64_t st_nlink; |
|||
uint64_t st_uid; |
|||
uint64_t st_gid; |
|||
uint64_t st_rdev; |
|||
uint64_t st_ino; |
|||
uint64_t st_size; |
|||
uint64_t st_blksize; |
|||
uint64_t st_blocks; |
|||
uint64_t st_flags; |
|||
uint64_t st_gen; |
|||
uv_timespec_t st_atim; |
|||
uv_timespec_t st_mtim; |
|||
uv_timespec_t st_ctim; |
|||
uv_timespec_t st_birthtim; |
|||
} uv_stat_t; |
|||
|
|||
.. c:type:: uv_fs_type |
|||
|
|||
Filesystem request type. |
|||
|
|||
:: |
|||
|
|||
typedef enum { |
|||
UV_FS_UNKNOWN = -1, |
|||
UV_FS_CUSTOM, |
|||
UV_FS_OPEN, |
|||
UV_FS_CLOSE, |
|||
UV_FS_READ, |
|||
UV_FS_WRITE, |
|||
UV_FS_SENDFILE, |
|||
UV_FS_STAT, |
|||
UV_FS_LSTAT, |
|||
UV_FS_FSTAT, |
|||
UV_FS_FTRUNCATE, |
|||
UV_FS_UTIME, |
|||
UV_FS_FUTIME, |
|||
UV_FS_CHMOD, |
|||
UV_FS_FCHMOD, |
|||
UV_FS_FSYNC, |
|||
UV_FS_FDATASYNC, |
|||
UV_FS_UNLINK, |
|||
UV_FS_RMDIR, |
|||
UV_FS_MKDIR, |
|||
UV_FS_MKDTEMP, |
|||
UV_FS_RENAME, |
|||
UV_FS_READDIR, |
|||
UV_FS_LINK, |
|||
UV_FS_SYMLINK, |
|||
UV_FS_READLINK, |
|||
UV_FS_CHOWN, |
|||
UV_FS_FCHOWN |
|||
} uv_fs_type; |
|||
|
|||
.. c:type:: uv_dirent_t |
|||
|
|||
Cross platform (reduced) equivalent of ``struct dirent``. |
|||
Used in :c:func:`uv_fs_readdir_next`. |
|||
|
|||
:: |
|||
|
|||
typedef enum { |
|||
UV_DIRENT_UNKNOWN, |
|||
UV_DIRENT_FILE, |
|||
UV_DIRENT_DIR, |
|||
UV_DIRENT_LINK, |
|||
UV_DIRENT_FIFO, |
|||
UV_DIRENT_SOCKET, |
|||
UV_DIRENT_CHAR, |
|||
UV_DIRENT_BLOCK |
|||
} uv_dirent_type_t; |
|||
|
|||
typedef struct uv_dirent_s { |
|||
const char* name; |
|||
uv_dirent_type_t type; |
|||
} uv_dirent_t; |
|||
|
|||
|
|||
Public members |
|||
^^^^^^^^^^^^^^ |
|||
|
|||
.. c:member:: uv_loop_t* uv_fs_t.loop |
|||
|
|||
Loop that started this request and where completion will be reported. |
|||
Readonly. |
|||
|
|||
.. c:member:: uv_fs_type uv_fs_t.fs_type |
|||
|
|||
FS request type. |
|||
|
|||
.. c:member:: const char* uv_fs_t.path |
|||
|
|||
Path affecting the request. |
|||
|
|||
.. c:member:: ssize_t uv_fs_t.result |
|||
|
|||
Result of the request. < 0 means error, success otherwise. On requests such |
|||
as :c:func:`uv_fs_read` or :c:func:`uv_fs_write` it indicates the amount of |
|||
data that was read or written, respectively. |
|||
|
|||
.. c:member:: uv_stat_t uv_fs_t.statbuf |
|||
|
|||
Stores the result of :c:func:`uv_fs_stat` and other stat requests. |
|||
|
|||
.. c:member:: void* uv_fs_t.ptr |
|||
|
|||
Stores the result of :c:func:`uv_fs_readlink` and serves as an alias to |
|||
`statbuf`. |
|||
|
|||
.. seealso:: The :c:type:`uv_req_t` members also apply. |
|||
|
|||
|
|||
API |
|||
--- |
|||
|
|||
.. c:function:: void uv_fs_req_cleanup(uv_fs_t* req) |
|||
|
|||
Cleanup request. Must be called after a request is finished to deallocate |
|||
any memory libuv might have allocated. |
|||
|
|||
.. c:function:: int uv_fs_close(uv_loop_t* loop, uv_fs_t* req, uv_file file, uv_fs_cb cb) |
|||
|
|||
Equivalent to ``close(2)``. |
|||
|
|||
.. c:function:: int uv_fs_open(uv_loop_t* loop, uv_fs_t* req, const char* path, int flags, int mode, uv_fs_cb cb) |
|||
|
|||
Equivalent to ``open(2)``. |
|||
|
|||
.. c:function:: int uv_fs_read(uv_loop_t* loop, uv_fs_t* req, uv_file file, const uv_buf_t bufs[], unsigned int nbufs, int64_t offset, uv_fs_cb cb) |
|||
|
|||
Equivalent to ``preadv(2)``. |
|||
|
|||
.. c:function:: int uv_fs_unlink(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb) |
|||
|
|||
Equivalent to ``unlink(2)``. |
|||
|
|||
.. c:function:: int uv_fs_write(uv_loop_t* loop, uv_fs_t* req, uv_file file, const uv_buf_t bufs[], unsigned int nbufs, int64_t offset, uv_fs_cb cb) |
|||
|
|||
Equivalent to ``pwritev(2)``. |
|||
|
|||
.. c:function:: int uv_fs_mkdir(uv_loop_t* loop, uv_fs_t* req, const char* path, int mode, uv_fs_cb cb) |
|||
|
|||
Equivalent to ``mkdir(2)``. |
|||
|
|||
.. note:: |
|||
`mode` is currently not implemented on Windows. |
|||
|
|||
.. c:function:: int uv_fs_mkdtemp(uv_loop_t* loop, uv_fs_t* req, const char* tpl, uv_fs_cb cb) |
|||
|
|||
Equivalent to ``mkdtemp(3)``. |
|||
|
|||
.. c:function:: int uv_fs_rmdir(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb) |
|||
|
|||
Equivalent to ``rmdir(2)``. |
|||
|
|||
.. c:function:: int uv_fs_readdir(uv_loop_t* loop, uv_fs_t* req, const char* path, int flags, uv_fs_cb cb) |
|||
.. c:function:: int uv_fs_readdir_next(uv_fs_t* req, uv_dirent_t* ent) |
|||
|
|||
Equivalent to ``readdir(2)``, with a slightly different API. Once the callback |
|||
for the request is called, the user can use :c:func:`uv_fs_readdir_next` to |
|||
get `ent` populated with the next directory entry data. When there are no |
|||
more entries ``UV_EOF`` will be returned. |
|||
|
|||
.. c:function:: int uv_fs_stat(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb) |
|||
.. c:function:: int uv_fs_fstat(uv_loop_t* loop, uv_fs_t* req, uv_file file, uv_fs_cb cb) |
|||
.. c:function:: int uv_fs_lstat(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb) |
|||
|
|||
Equivalent to ``(f/l)stat(2)``. |
|||
|
|||
.. c:function:: int uv_fs_rename(uv_loop_t* loop, uv_fs_t* req, const char* path, const char* new_path, uv_fs_cb cb) |
|||
|
|||
Equivalent to ``rename(2)``. |
|||
|
|||
.. c:function:: int uv_fs_fsync(uv_loop_t* loop, uv_fs_t* req, uv_file file, uv_fs_cb cb) |
|||
|
|||
Equivalent to ``fsync(2)``. |
|||
|
|||
.. c:function:: int uv_fs_fdatasync(uv_loop_t* loop, uv_fs_t* req, uv_file file, uv_fs_cb cb) |
|||
|
|||
Equivalent to ``fdatasync(2)``. |
|||
|
|||
.. c:function:: int uv_fs_ftruncate(uv_loop_t* loop, uv_fs_t* req, uv_file file, int64_t offset, uv_fs_cb cb) |
|||
|
|||
Equivalent to ``ftruncate(2)``. |
|||
|
|||
.. c:function:: int uv_fs_sendfile(uv_loop_t* loop, uv_fs_t* req, uv_file out_fd, uv_file in_fd, int64_t in_offset, size_t length, uv_fs_cb cb) |
|||
|
|||
Limited equivalent to ``sendfile(2)``. |
|||
|
|||
.. c:function:: int uv_fs_chmod(uv_loop_t* loop, uv_fs_t* req, const char* path, int mode, uv_fs_cb cb) |
|||
.. c:function:: int uv_fs_fchmod(uv_loop_t* loop, uv_fs_t* req, uv_file file, int mode, uv_fs_cb cb) |
|||
|
|||
Equivalent to ``(f)chmod(2)``. |
|||
|
|||
.. c:function:: int uv_fs_utime(uv_loop_t* loop, uv_fs_t* req, const char* path, double atime, double mtime, uv_fs_cb cb) |
|||
.. c:function:: int uv_fs_futime(uv_loop_t* loop, uv_fs_t* req, uv_file file, double atime, double mtime, uv_fs_cb cb) |
|||
|
|||
Equivalent to ``(f)utime(s)(2)``. |
|||
|
|||
.. c:function:: int uv_fs_link(uv_loop_t* loop, uv_fs_t* req, const char* path, const char* new_path, uv_fs_cb cb) |
|||
|
|||
Equivalent to ``link(2)``. |
|||
|
|||
.. c:function:: int uv_fs_symlink(uv_loop_t* loop, uv_fs_t* req, const char* path, const char* new_path, int flags, uv_fs_cb cb) |
|||
|
|||
Equivalent to ``symlink(2)``. |
|||
|
|||
.. note:: |
|||
On Windows the `flags` parameter can be specified to control how the symlink will |
|||
be created: |
|||
|
|||
* ``UV_FS_SYMLINK_DIR``: indicates that `path` points to a directory. |
|||
|
|||
* ``UV_FS_SYMLINK_JUNCTION``: request that the symlink is created |
|||
using junktion points. |
|||
|
|||
.. c:function:: int uv_fs_readlink(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb) |
|||
|
|||
Equivalent to ``readlink(2)``. |
|||
|
|||
.. c:function:: int uv_fs_chown(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_uid_t uid, uv_gid_t gid, uv_fs_cb cb) |
|||
.. c:function:: int uv_fs_fchown(uv_loop_t* loop, uv_fs_t* req, uv_file file, uv_uid_t uid, uv_gid_t gid, uv_fs_cb cb) |
|||
|
|||
Equivalent to ``(f)chown(2)``. |
|||
|
|||
.. note:: |
|||
These functions are not implemented on Windows. |
|||
|
|||
.. seealso:: The :c:type:`uv_req_t` API functions also apply. |
|||
@ -0,0 +1,102 @@ |
|||
|
|||
.. _fs_event: |
|||
|
|||
:c:type:`uv_fs_event_t` --- FS Event handle |
|||
=========================================== |
|||
|
|||
FS Event handles allow the user to monitor a given path for changes, for example, |
|||
if the file was renamed or there was a generic change in it. This handle uses |
|||
the best backend for the job on each platform. |
|||
|
|||
|
|||
Data types |
|||
---------- |
|||
|
|||
.. c:type:: uv_fs_event_t |
|||
|
|||
FS Event handle type. |
|||
|
|||
.. c:type:: void (*uv_fs_event_cb)(uv_fs_event_t* handle, const char* filename, int events, int status) |
|||
|
|||
Callback passed to :c:func:`uv_fs_event_start` which will be called repeatedly |
|||
after the handle is started. If the handle was started with a directory the |
|||
`filename` parameter will be a relative path to a file contained in the directory. |
|||
The `events` parameter is an ORed mask of :c:type:`uv_fs_event` elements. |
|||
|
|||
.. c:type:: uv_fs_event |
|||
|
|||
Event types that :c:type:`uv_fs_event_t` handles monitor. |
|||
|
|||
:: |
|||
|
|||
enum uv_fs_event { |
|||
UV_RENAME = 1, |
|||
UV_CHANGE = 2 |
|||
}; |
|||
|
|||
.. c:type:: uv_fs_event_flags |
|||
|
|||
Flags that can be passed to :c:func:`uv_fs_event_start` to control its |
|||
behavior. |
|||
|
|||
:: |
|||
|
|||
enum uv_fs_event_flags { |
|||
/* |
|||
* By default, if the fs event watcher is given a directory name, we will |
|||
* watch for all events in that directory. This flags overrides this behavior |
|||
* and makes fs_event report only changes to the directory entry itself. This |
|||
* flag does not affect individual files watched. |
|||
* This flag is currently not implemented yet on any backend. |
|||
*/ |
|||
UV_FS_EVENT_WATCH_ENTRY = 1, |
|||
/* |
|||
* By default uv_fs_event will try to use a kernel interface such as inotify |
|||
* or kqueue to detect events. This may not work on remote filesystems such |
|||
* as NFS mounts. This flag makes fs_event fall back to calling stat() on a |
|||
* regular interval. |
|||
* This flag is currently not implemented yet on any backend. |
|||
*/ |
|||
UV_FS_EVENT_STAT = 2, |
|||
/* |
|||
* By default, event watcher, when watching directory, is not registering |
|||
* (is ignoring) changes in it's subdirectories. |
|||
* This flag will override this behaviour on platforms that support it. |
|||
*/ |
|||
UV_FS_EVENT_RECURSIVE = 4 |
|||
}; |
|||
|
|||
|
|||
Public members |
|||
^^^^^^^^^^^^^^ |
|||
|
|||
N/A |
|||
|
|||
.. seealso:: The :c:type:`uv_handle_t` members also apply. |
|||
|
|||
|
|||
API |
|||
--- |
|||
|
|||
.. c:function:: int uv_fs_event_init(uv_loop_t* loop, uv_fs_event_t* handle) |
|||
|
|||
Initialize the handle. |
|||
|
|||
.. c:function:: int uv_fs_event_start(uv_fs_event_t* handle, uv_fs_event_cb cb, const char* path, unsigned int flags) |
|||
|
|||
Start the handle with the given callback, which will watch the specified |
|||
`path` for changes. `flags` can be an ORed mask of :c:type:`uv_fs_event_flags`. |
|||
|
|||
.. c:function:: int uv_fs_event_stop(uv_fs_event_t* handle) |
|||
|
|||
Stop the handle, the callback will no longer be called. |
|||
|
|||
.. c:function:: int uv_fs_event_getpath(uv_fs_event_t* handle, char* buf, size_t* len) |
|||
|
|||
Get the path being monitored by the handle. The buffer must be preallocated |
|||
by the user. Returns 0 on success or an error code < 0 in case of failure. |
|||
On sucess, `buf` will contain the path and `len` its length. If the buffer |
|||
is not big enough UV_ENOBUFS will be returned and len will be set to the |
|||
required size. |
|||
|
|||
.. seealso:: The :c:type:`uv_handle_t` API functions also apply. |
|||
@ -0,0 +1,65 @@ |
|||
|
|||
.. _fs_poll: |
|||
|
|||
:c:type:`uv_fs_poll_t` --- FS Poll handle |
|||
========================================= |
|||
|
|||
FS Poll handles allow the user to monitor a given path for changes. Unlike |
|||
:c:type:`uv_fs_event_t`, fs poll handles use `stat` to detect when a file has |
|||
changed so they can work on file systems where fs event handles can't. |
|||
|
|||
|
|||
Data types |
|||
---------- |
|||
|
|||
.. c:type:: uv_fs_poll_t |
|||
|
|||
FS Poll handle type. |
|||
|
|||
.. c:type:: void (*uv_fs_poll_cb)(uv_fs_poll_t* handle, int status, const uv_stat_t* prev, const uv_stat_t* curr) |
|||
|
|||
Callback passed to :c:func:`uv_fs_poll_start` which will be called repeatedly |
|||
after the handle is started, when any change happens to the monitored path. |
|||
|
|||
The callback is invoked with `status < 0` if `path` does not exist |
|||
or is inaccessible. The watcher is *not* stopped but your callback is |
|||
not called again until something changes (e.g. when the file is created |
|||
or the error reason changes). |
|||
|
|||
When `status == 0`, the callback receives pointers to the old and new |
|||
:c:type:`uv_stat_t` structs. They are valid for the duration of the |
|||
callback only. |
|||
|
|||
|
|||
Public members |
|||
^^^^^^^^^^^^^^ |
|||
|
|||
N/A |
|||
|
|||
.. seealso:: The :c:type:`uv_handle_t` members also apply. |
|||
|
|||
|
|||
API |
|||
--- |
|||
|
|||
.. c:function:: int uv_fs_poll_start(uv_fs_poll_t* handle, uv_fs_poll_cb poll_cb, const char* path, unsigned int interval) |
|||
|
|||
Check the file at `path` for changes every `interval` milliseconds. |
|||
|
|||
.. note:: |
|||
For maximum portability, use multi-second intervals. Sub-second intervals will not detect |
|||
all changes on many file systems. |
|||
|
|||
.. c:function:: int uv_fs_poll_stop(uv_fs_poll_t* handle) |
|||
|
|||
Stop the handle, the callback will no longer be called. |
|||
|
|||
.. c:function:: int uv_fs_poll_getpath(uv_fs_poll_t* handle, char* buf, size_t* len) |
|||
|
|||
Get the path being monitored by the handle. The buffer must be preallocated |
|||
by the user. Returns 0 on success or an error code < 0 in case of failure. |
|||
On sucess, `buf` will contain the path and `len` its length. If the buffer |
|||
is not big enough UV_ENOBUFS will be returned and len will be set to the |
|||
required size. |
|||
|
|||
.. seealso:: The :c:type:`uv_handle_t` API functions also apply. |
|||
@ -0,0 +1,172 @@ |
|||
|
|||
.. _handle: |
|||
|
|||
:c:type:`uv_handle_t` --- Base handle |
|||
===================================== |
|||
|
|||
`uv_handle_t` is the base type for all libuv handle types. |
|||
|
|||
Strcutures are aligned so that any libuv handle can be cast to `uv_handle_t`. |
|||
All API functions defined here work with any handle type. |
|||
|
|||
|
|||
Data types |
|||
---------- |
|||
|
|||
.. c:type:: uv_handle_t |
|||
|
|||
The base libuv handle type. |
|||
|
|||
.. c:type:: uv_any_handle |
|||
|
|||
Union of all handle types. |
|||
|
|||
.. c:type:: void (*uv_close_cb)(uv_handle_t* handle) |
|||
|
|||
Type definition for callback passed to :c:func:`uv_close`. |
|||
|
|||
|
|||
Public members |
|||
^^^^^^^^^^^^^^ |
|||
|
|||
.. c:member:: uv_loop_t* uv_handle_t.loop |
|||
|
|||
Pointer to the :c:type:`uv_loop_t` where the handle is running on. Readonly. |
|||
|
|||
.. c:member:: void* uv_handle_t.data |
|||
|
|||
Space for user-defined arbitrary data. libuv does not use this field. |
|||
|
|||
|
|||
API |
|||
--- |
|||
|
|||
.. c:function:: int uv_is_active(const uv_handle_t* handle) |
|||
|
|||
Returns non-zero if the handle is active, zero 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(), etc. |
|||
|
|||
Rule of thumb: if a handle of type `uv_foo_t` has a `uv_foo_start()` |
|||
function, then it's active from the moment that function is called. |
|||
Likewise, `uv_foo_stop()` deactivates the handle again. |
|||
|
|||
.. c:function:: int uv_is_closing(const uv_handle_t* handle) |
|||
|
|||
Returns non-zero if the handle is closing or closed, zero otherwise. |
|||
|
|||
.. note:: |
|||
This function should only be used between the initialization of the handle and the |
|||
arrival of the close callback. |
|||
|
|||
.. c:function:: void uv_close(uv_handle_t* handle, uv_close_cb close_cb) |
|||
|
|||
Request handle to be closed. `close_cb` 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 |
|||
`close_cb` 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 status=UV_ECANCELED. |
|||
|
|||
.. c:function:: void uv_ref(uv_handle_t* handle) |
|||
|
|||
Reference the given handle. References are idempotent, that is, if a handle |
|||
is already referenced calling this function again will have no effect. |
|||
|
|||
See :ref:`refcount`. |
|||
|
|||
.. c:function:: void uv_unref(uv_handle_t* handle) |
|||
|
|||
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 :ref:`refcount`. |
|||
|
|||
.. c:function:: int uv_has_ref(const uv_handle_t* handle) |
|||
|
|||
Returns non-zero if the handle referenced, zero otherwise. |
|||
|
|||
See :ref:`refcount`. |
|||
|
|||
.. c:function:: size_t uv_handle_size(uv_handle_type type) |
|||
|
|||
Returns the size of the given handle type. Useful for FFI binding writers |
|||
who don't want to know the structure layout. |
|||
|
|||
|
|||
Miscellaneous API functions |
|||
--------------------------- |
|||
|
|||
The following API functions take a :c:type:`uv_handle_t` argument but they work |
|||
just for some handle types. |
|||
|
|||
.. c:function:: int uv_send_buffer_size(uv_handle_t* handle, int* value) |
|||
|
|||
Gets or sets the size of the send buffer that the operating |
|||
system uses for the socket. |
|||
|
|||
If `*value` == 0, it will return the current send buffer size, |
|||
otherwise it will use `*value` to set the new send buffer size. |
|||
|
|||
This function works for TCP, pipe and UDP handles on Unix and for TCP and |
|||
UDP handles on Windows. |
|||
|
|||
.. note:: |
|||
Linux will set double the size and return double the size of the original set value. |
|||
|
|||
.. c:function:: int uv_recv_buffer_size(uv_handle_t* handle, int* value) |
|||
|
|||
Gets or sets the size of the receive buffer that the operating |
|||
system uses for the socket. |
|||
|
|||
If `*value` == 0, it will return the current receive buffer size, |
|||
otherwise it will use `*value` to set the new receive buffer size. |
|||
|
|||
This function works for TCP, pipe and UDP handles on Unix and for TCP and |
|||
UDP handles on Windows. |
|||
|
|||
.. note:: |
|||
Linux will set double the size and return double the size of the original set value. |
|||
|
|||
.. c:function:: int uv_fileno(const uv_handle_t* handle, uv_os_fd_t* fd) |
|||
|
|||
Gets the platform dependent file descriptor equivalent. |
|||
|
|||
The following handles are supported: TCP, pipes, TTY, UDP and poll. Passing |
|||
any other handle type will fail with `UV_EINVAL`. |
|||
|
|||
If a handle doesn't have an attached file descriptor yet or the handle |
|||
itself has been closed, this function will return `UV_EBADF`. |
|||
|
|||
.. warning:: |
|||
Be very careful when using this function. libuv assumes it's in control of the file |
|||
descriptor so any change to it may lead to malfunction. |
|||
|
|||
|
|||
.. _refcount: |
|||
|
|||
Reference counting |
|||
------------------ |
|||
|
|||
The libuv event loop (if run in the default mode) will run until there are no |
|||
active `and` referenced handles left. The user can force the loop to exit early |
|||
by unreferencing handles which are active, for example by calling :c:func:`uv_unref` |
|||
after calling :c:func:`uv_timer_start`. |
|||
|
|||
A handle can be referenced or unreferenced, the refcounting scheme doesn't use |
|||
a counter, so both operations are idempotent. |
|||
|
|||
All handles are referenced when active by default, see :c:func:`uv_is_active` |
|||
for a more detailed explanation on what being `active` involves. |
|||
@ -0,0 +1,54 @@ |
|||
|
|||
.. _idle: |
|||
|
|||
:c:type:`uv_idle_t` --- Idle handle |
|||
=================================== |
|||
|
|||
Idle handles will run the given callback once per loop iteration, right |
|||
before the :c:type:`uv_prepare_t` handles. |
|||
|
|||
.. note:: |
|||
The notable difference with prepare handles is that when there are active idle handles, |
|||
the loop will perform a zero timeout poll instead of blocking for i/o. |
|||
|
|||
.. warning:: |
|||
Despite the name, idle handles will get their callbacks called on every loop iteration, |
|||
not when the loop is actually "idle". |
|||
|
|||
|
|||
Data types |
|||
---------- |
|||
|
|||
.. c:type:: uv_idle_t |
|||
|
|||
Idle handle type. |
|||
|
|||
.. c:type:: void (*uv_idle_cb)(uv_idle_t* handle) |
|||
|
|||
Type definition for callback passed to :c:func:`uv_idle_start`. |
|||
|
|||
|
|||
Public members |
|||
^^^^^^^^^^^^^^ |
|||
|
|||
N/A |
|||
|
|||
.. seealso:: The :c:type:`uv_handle_t` members also apply. |
|||
|
|||
|
|||
API |
|||
--- |
|||
|
|||
.. c:function:: int uv_idle_init(uv_loop_t*, uv_idle_t* idle) |
|||
|
|||
Initialize the handle. |
|||
|
|||
.. c:function:: int uv_idle_start(uv_idle_t* idle, uv_idle_cb cb) |
|||
|
|||
Start the handle with the given callback. |
|||
|
|||
.. c:function:: int uv_idle_stop(uv_idle_t* idle) |
|||
|
|||
Stop the handle, the callback will no longer be called. |
|||
|
|||
.. seealso:: The :c:type:`uv_handle_t` API functions also apply. |
|||
@ -0,0 +1,84 @@ |
|||
|
|||
Welcome to the libuv API documentation |
|||
====================================== |
|||
|
|||
Overview |
|||
-------- |
|||
|
|||
libuv is a multi-platform support library with a focus on asynchronous I/O. It |
|||
was primarily developed for use by `Node.js`_, but it's also used by Mozilla's |
|||
`Rust language`_, `Luvit`_, `Julia`_, `pyuv`_, and `others`_. |
|||
|
|||
.. note:: |
|||
In case you find errors in this documentation you can help by sending |
|||
`pull requests <https://github.com/joyent/libuv>`_! |
|||
|
|||
.. _Node.js: http://nodejs.org |
|||
.. _Rust language: http://www.rust-lang.org |
|||
.. _Luvit: http://luvit.io |
|||
.. _Julia: http://julialang.org |
|||
.. _pyuv: https://github.com/saghul/pyuv |
|||
.. _others: https://github.com/joyent/libuv/wiki/Projects-that-use-libuv |
|||
|
|||
|
|||
Features |
|||
-------- |
|||
|
|||
* Full-featured event loop backed by epoll, kqueue, IOCP, event ports. |
|||
* Asynchronous TCP and UDP sockets |
|||
* Asynchronous DNS resolution |
|||
* Asynchronous file and file system operations |
|||
* File system events |
|||
* ANSI escape code controlled TTY |
|||
* IPC with socket sharing, using Unix domain sockets or named pipes (Windows) |
|||
* Child processes |
|||
* Thread pool |
|||
* Signal handling |
|||
* High resolution clock |
|||
* Threading and synchronization primitives |
|||
|
|||
|
|||
Downloads |
|||
--------- |
|||
|
|||
libuv can be downloaded from `here <http://dist.libuv.org/dist/>`_. |
|||
|
|||
|
|||
Installation |
|||
------------ |
|||
|
|||
Installation instructions can be found on `the README <https://github.com/joyent/libuv/blob/master/README.md>`_. |
|||
|
|||
|
|||
Documentation |
|||
------------- |
|||
|
|||
.. toctree:: |
|||
:maxdepth: 1 |
|||
|
|||
design |
|||
errors |
|||
loop |
|||
handle |
|||
request |
|||
timer |
|||
prepare |
|||
check |
|||
idle |
|||
async |
|||
poll |
|||
signal |
|||
process |
|||
stream |
|||
tcp |
|||
pipe |
|||
tty |
|||
udp |
|||
fs_event |
|||
fs_poll |
|||
fs |
|||
threadpool |
|||
dns |
|||
dll |
|||
threading |
|||
misc |
|||
@ -0,0 +1,137 @@ |
|||
|
|||
.. _loop: |
|||
|
|||
:c:type:`uv_loop_t` --- Event loop |
|||
================================== |
|||
|
|||
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. |
|||
|
|||
|
|||
Data types |
|||
---------- |
|||
|
|||
.. c:type:: uv_loop_t |
|||
|
|||
Loop data type. |
|||
|
|||
.. c:type:: uv_run_mode |
|||
|
|||
Mode used to run the loop with :c:func:`uv_run`. |
|||
|
|||
:: |
|||
|
|||
typedef enum { |
|||
UV_RUN_DEFAULT = 0, |
|||
UV_RUN_ONCE, |
|||
UV_RUN_NOWAIT |
|||
} uv_run_mode; |
|||
|
|||
.. c:type:: void (*uv_walk_cb)(uv_handle_t* handle, void* arg) |
|||
|
|||
Type definition for callback passed to :c:func:`uv_walk`. |
|||
|
|||
|
|||
Public members |
|||
^^^^^^^^^^^^^^ |
|||
|
|||
.. c:member:: void* uv_loop_t.data |
|||
|
|||
Space for user-defined arbitrary data. libuv does not use this field. |
|||
|
|||
|
|||
API |
|||
--- |
|||
|
|||
.. c:function:: int uv_loop_init(uv_loop_t* loop) |
|||
|
|||
Initializes the given `uv_loop_t` structure. |
|||
|
|||
.. c:function:: int uv_loop_close(uv_loop_t* loop) |
|||
|
|||
Closes all internal loop resources. This function must only be called once |
|||
the loop has finished its execution or it will return UV_EBUSY. After this |
|||
function returns the user shall free the memory allocated for the loop. |
|||
|
|||
.. c:function:: uv_loop_t* uv_default_loop(void) |
|||
|
|||
Returns the initialized default loop. It may return NULL in case of |
|||
allocation failture. |
|||
|
|||
.. c:function:: int uv_run(uv_loop_t* loop, uv_run_mode mode) |
|||
|
|||
This function runs the event loop. It will act differently depending on the |
|||
specified mode: |
|||
|
|||
- UV_RUN_DEFAULT: Runs the event loop until there are no more active and |
|||
referenced handles or requests. Always returns zero. |
|||
- UV_RUN_ONCE: Poll for i/o once. Note that this function blocks if |
|||
there are no pending callbacks. Returns zero when done (no active handles |
|||
or requests left), or non-zero if more callbacks are expected (meaning |
|||
you should run the event loop again sometime in the future). |
|||
- UV_RUN_NOWAIT: Poll for i/o once but don't block if there are no |
|||
pending callbacks. Returns zero if done (no active handles |
|||
or requests left), or non-zero if more callbacks are expected (meaning |
|||
you should run the event loop again sometime in the future). |
|||
|
|||
.. c:function:: int uv_loop_alive(const uv_loop_t* loop) |
|||
|
|||
Returns non-zero if there are active handles or request in the loop. |
|||
|
|||
.. c:function:: void uv_stop(uv_loop_t* loop) |
|||
|
|||
Stop the event loop, causing :c:func:`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. |
|||
|
|||
.. c:function:: size_t uv_loop_size(void) |
|||
|
|||
Returns the size of the `uv_loop_t` structure. Useful for FFI binding |
|||
writers who don't want to know the structure layout. |
|||
|
|||
.. c:function:: int uv_backend_fd(const uv_loop_t* loop) |
|||
|
|||
Get backend file descriptor. Only kqueue, epoll and event ports are |
|||
supported. |
|||
|
|||
This can be used in conjunction with `uv_run(loop, UV_RUN_NOWAIT)` to |
|||
poll in one thread and run the event loop's callbacks in another see |
|||
test/test-embed.c for an example. |
|||
|
|||
.. note:: |
|||
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. |
|||
|
|||
.. c:function:: int uv_backend_timeout(const uv_loop_t* loop) |
|||
|
|||
Get the poll timeout. The return value is in milliseconds, or -1 for no |
|||
timeout. |
|||
|
|||
.. c:function:: uint64_t uv_now(const uv_loop_t* loop) |
|||
|
|||
Return the current timestamp in milliseconds. The timestamp is cached at |
|||
the start of the event loop tick, see :c:func:`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. |
|||
|
|||
.. note:: |
|||
Use :c:func:`uv_hrtime` if you need sub-millisecond granularity. |
|||
|
|||
.. c:function:: void uv_update_time(uv_loop_t* loop) |
|||
|
|||
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. |
|||
|
|||
.. c:function:: void uv_walk(uv_loop_t* loop, uv_walk_cb walk_cb, void* arg) |
|||
|
|||
Walk the list of handles: `walk_cb` will be executed with the given `arg`. |
|||
@ -0,0 +1,228 @@ |
|||
|
|||
.. _misc: |
|||
|
|||
Miscelaneous utilities |
|||
====================== |
|||
|
|||
This section contains miscelaneous functions that don't really belong in any |
|||
other section. |
|||
|
|||
|
|||
Data types |
|||
---------- |
|||
|
|||
.. c:type:: uv_buf_t |
|||
|
|||
Buffer data type. |
|||
|
|||
.. c:type:: uv_file |
|||
|
|||
Cross platform representation of a file handle. |
|||
|
|||
.. c:type:: uv_os_sock_t |
|||
|
|||
Cross platform representation of a socket handle. |
|||
|
|||
.. c:type:: uv_os_fd_t |
|||
|
|||
Abstract representation of a file descriptor. On Unix systems this is a |
|||
`typedef` of `int` and on Windows fa `HANDLE`. |
|||
|
|||
.. c:type:: uv_rusage_t |
|||
|
|||
Data type for resource usage results. |
|||
|
|||
:: |
|||
|
|||
typedef struct { |
|||
uv_timeval_t ru_utime; /* user CPU time used */ |
|||
uv_timeval_t ru_stime; /* system CPU time used */ |
|||
uint64_t ru_maxrss; /* maximum resident set size */ |
|||
uint64_t ru_ixrss; /* integral shared memory size */ |
|||
uint64_t ru_idrss; /* integral unshared data size */ |
|||
uint64_t ru_isrss; /* integral unshared stack size */ |
|||
uint64_t ru_minflt; /* page reclaims (soft page faults) */ |
|||
uint64_t ru_majflt; /* page faults (hard page faults) */ |
|||
uint64_t ru_nswap; /* swaps */ |
|||
uint64_t ru_inblock; /* block input operations */ |
|||
uint64_t ru_oublock; /* block output operations */ |
|||
uint64_t ru_msgsnd; /* IPC messages sent */ |
|||
uint64_t ru_msgrcv; /* IPC messages received */ |
|||
uint64_t ru_nsignals; /* signals received */ |
|||
uint64_t ru_nvcsw; /* voluntary context switches */ |
|||
uint64_t ru_nivcsw; /* involuntary context switches */ |
|||
} uv_rusage_t; |
|||
|
|||
.. c:type:: uv_cpu_info_t |
|||
|
|||
Data type for CPU information. |
|||
|
|||
:: |
|||
|
|||
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; |
|||
|
|||
.. c:type:: uv_interface_address_t |
|||
|
|||
Data type for interface addresses. |
|||
|
|||
:: |
|||
|
|||
typedef struct uv_interface_address_s { |
|||
char* name; |
|||
char phys_addr[6]; |
|||
int is_internal; |
|||
union { |
|||
struct sockaddr_in address4; |
|||
struct sockaddr_in6 address6; |
|||
} address; |
|||
union { |
|||
struct sockaddr_in netmask4; |
|||
struct sockaddr_in6 netmask6; |
|||
} netmask; |
|||
} uv_interface_address_t; |
|||
|
|||
|
|||
API |
|||
--- |
|||
|
|||
.. c:function:: uv_handle_type uv_guess_handle(uv_file file) |
|||
|
|||
Used to detect what type of stream should be used with a given file |
|||
descriptor. Usually this will be used during initialization to guess the |
|||
type of the stdio streams. |
|||
|
|||
For ``isatty()`` functionality use this function and test for ``UV_TTY``. |
|||
|
|||
.. c:function:: unsigned int uv_version(void) |
|||
|
|||
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. E.g. for libuv 1.2.3 this would return 0x010203. |
|||
|
|||
.. c:function:: const char* uv_version_string(void) |
|||
|
|||
Returns the libuv version number as a string. For non-release versions |
|||
"-pre" is appended, so the version number could be "1.2.3-pre". |
|||
|
|||
.. c:function:: uv_buf_t uv_buf_init(char* base, unsigned int len) |
|||
|
|||
Constructor for :c:type:`uv_buf_t`. |
|||
|
|||
Due to platform differences the user cannot rely on the ordering of the |
|||
`base` and `len` members of the uv_buf_t struct. The user is responsible for |
|||
freeing `base` after the uv_buf_t is done. Return struct passed by value. |
|||
|
|||
.. c:function:: char** uv_setup_args(int argc, char** argv) |
|||
|
|||
Store the program arguments. Required for getting / setting the process title. |
|||
|
|||
.. c:function:: int uv_get_process_title(char* buffer, size_t size) |
|||
|
|||
Gets the title of the current process. |
|||
|
|||
.. c:function:: int uv_set_process_title(const char* title) |
|||
|
|||
Sets the current process title. |
|||
|
|||
.. c:function:: int uv_resident_set_memory(size_t* rss) |
|||
|
|||
Gets the resident set size (RSS) for the current process. |
|||
|
|||
.. c:function:: int uv_uptime(double* uptime) |
|||
|
|||
Gets the current system uptime. |
|||
|
|||
.. c:function:: int uv_getrusage(uv_rusage_t* rusage) |
|||
|
|||
Gets the resource usage measures for the current process. |
|||
|
|||
.. note:: |
|||
On Windows not all fields are set, the unsupported fields are filled with zeroes. |
|||
|
|||
.. c:function:: int uv_cpu_info(uv_cpu_info_t** cpu_infos, int* count) |
|||
|
|||
Gets information about the CPUs on the system. The `cpu_infos` array will |
|||
have `count` elements and needs to be freed with :c:func:`uv_free_cpu_info`. |
|||
|
|||
.. c:function:: void uv_free_cpu_info(uv_cpu_info_t* cpu_infos, int count) |
|||
|
|||
Frees the `cpu_infos` array previously allocated with :c:func:`uv_cpu_info`. |
|||
|
|||
.. c:function:: int uv_interface_addresses(uv_interface_address_t** addresses, int* count) |
|||
|
|||
Gets address information about the network interfaces on the system. An |
|||
array of `count` elements is allocated and returned in `addresses`. It must |
|||
be freed by the user, calling :c:func:`uv_free_interface_addresses`. |
|||
|
|||
.. c:function:: void uv_free_interface_addresses(uv_interface_address_t* addresses, int count) |
|||
|
|||
Free an array of :c:type:`uv_interface_address_t` which was returned by |
|||
:c:func:`uv_interface_addresses`. |
|||
|
|||
.. c:function:: void uv_loadavg(double avg[3]) |
|||
|
|||
Gets the load average. See: http://en.wikipedia.org/wiki/Load_(computing) |
|||
|
|||
.. note:: |
|||
Returns [0,0,0] on Windows (i.e., it's not implemented). |
|||
|
|||
.. c:function:: int uv_ip4_addr(const char* ip, int port, struct sockaddr_in* addr) |
|||
|
|||
Convert a string containing an IPv4 addresses to a binary structure. |
|||
|
|||
.. c:function:: int uv_ip6_addr(const char* ip, int port, struct sockaddr_in6* addr) |
|||
|
|||
Convert a string containing an IPv6 addresses to a binary structure. |
|||
|
|||
.. c:function:: int uv_ip4_name(const struct sockaddr_in* src, char* dst, size_t size) |
|||
|
|||
Convert a binary structure containing an IPv4 addres to a string. |
|||
|
|||
.. c:function:: int uv_ip6_name(const struct sockaddr_in6* src, char* dst, size_t size) |
|||
|
|||
Convert a binary structure containing an IPv6 addres to a string. |
|||
|
|||
.. c:function:: int uv_inet_ntop(int af, const void* src, char* dst, size_t size) |
|||
.. c:function:: int uv_inet_pton(int af, const char* src, void* dst) |
|||
|
|||
Cross-platform IPv6-capable implementation of the 'standard' ``inet_ntop()`` |
|||
and ``inet_pton()`` functions. On success they return 0. In case of error |
|||
the target `dst` pointer is unmodified. |
|||
|
|||
.. c:function:: int uv_exepath(char* buffer, size_t* size) |
|||
|
|||
Gets the executable path. |
|||
|
|||
.. c:function:: int uv_cwd(char* buffer, size_t* size) |
|||
|
|||
Gets the current working directory. |
|||
|
|||
.. c:function:: int uv_chdir(const char* dir) |
|||
|
|||
Changes the current working directory. |
|||
|
|||
.. uint64_t uv_get_free_memory(void) |
|||
.. c:function:: uint64_t uv_get_total_memory(void) |
|||
|
|||
Gets memory information (in bytes). |
|||
|
|||
.. c:function:: uint64_t uv_hrtime(void) |
|||
|
|||
Returns the current high-resolution real time. This is expressed in |
|||
nanoseconds. It is relative to an arbitrary time in the past. It is not |
|||
related to the time of day and therefore not subject to clock drift. The |
|||
primary use is for measuring performance between intervals. |
|||
|
|||
.. note:: |
|||
Not every platform can support nanosecond resolution; however, this value will always |
|||
be in nanoseconds. |
|||
@ -0,0 +1,86 @@ |
|||
|
|||
.. _pipe: |
|||
|
|||
:c:type:`uv_pipe_t` --- Pipe handle |
|||
=================================== |
|||
|
|||
Pipe handles provide an abstraction over local domain sockets on Unix and named |
|||
pipes on Windows. |
|||
|
|||
:c:type:`uv_pipe_t` is a 'subclass' of :c:type:`uv_stream_t`. |
|||
|
|||
|
|||
Data types |
|||
---------- |
|||
|
|||
.. c:type:: uv_pipe_t |
|||
|
|||
Pipe handle type. |
|||
|
|||
|
|||
Public members |
|||
^^^^^^^^^^^^^^ |
|||
|
|||
N/A |
|||
|
|||
.. seealso:: The :c:type:`uv_stream_t` members also apply. |
|||
|
|||
|
|||
API |
|||
--- |
|||
|
|||
.. c:function:: int uv_pipe_init(uv_loop_t*, uv_pipe_t* handle, int ipc) |
|||
|
|||
Initialize a pipe handle. The `ipc` argument is a boolean to indicate if |
|||
this pipe will be used for handle passing between processes. |
|||
|
|||
.. c:function:: int uv_pipe_open(uv_pipe_t*, uv_file file) |
|||
|
|||
Open an existing file descriptor or HANDLE as a pipe. |
|||
|
|||
.. note:: |
|||
The user is responsible for setting the dile descriptor in non-blocking mode. |
|||
|
|||
.. c:function:: int uv_pipe_bind(uv_pipe_t* handle, const char* name) |
|||
|
|||
Bind the pipe to a file path (Unix) or a name (Windows). |
|||
|
|||
.. note:: |
|||
Paths on Unix get truncated to ``sizeof(sockaddr_un.sun_path)`` bytes, typically between |
|||
92 and 108 bytes. |
|||
|
|||
.. c:function:: void uv_pipe_connect(uv_connect_t* req, uv_pipe_t* handle, const char* name, uv_connect_cb cb) |
|||
|
|||
Connect to the Unix domain socket or the named pipe. |
|||
|
|||
.. note:: |
|||
Paths on Unix get truncated to ``sizeof(sockaddr_un.sun_path)`` bytes, typically between |
|||
92 and 108 bytes. |
|||
|
|||
.. c:function:: int uv_pipe_getsockname(const uv_pipe_t* handle, char* buf, size_t* len) |
|||
|
|||
Get the name of the Unix domain socket or the named pipe. |
|||
|
|||
A preallocated buffer must be provided. The len parameter holds the length |
|||
of the buffer and it's set to the number of bytes written to the buffer on |
|||
output. If the buffer is not big enough ``UV_ENOBUFS`` will be returned and |
|||
len will contain the required size. |
|||
|
|||
.. c:function:: void uv_pipe_pending_instances(uv_pipe_t* handle, int count) |
|||
|
|||
Set the number of pending pipe instance handles when the pipe server is |
|||
waiting for connections. |
|||
|
|||
.. note:: |
|||
This setting applies to Windows only. |
|||
|
|||
.. c:function:: int uv_pipe_pending_count(uv_pipe_t* handle) |
|||
.. c:function:: uv_handle_type uv_pipe_pending_type(uv_pipe_t* handle) |
|||
|
|||
Used to receive handles over IPC pipes. |
|||
|
|||
First - call :c:func:`uv_pipe_pending_count`, if it's > 0 then initialize |
|||
a handle of the given `type`, returned by :c:func:`uv_pipe_pending_type` |
|||
and call ``uv_accept(pipe, handle)``. |
|||
|
|||
.. seealso:: The :c:type:`uv_stream_t` API functions also apply. |
|||
@ -0,0 +1,99 @@ |
|||
|
|||
.. _poll: |
|||
|
|||
:c:type:`uv_poll_t` --- Poll handle |
|||
=================================== |
|||
|
|||
Poll handles are used to watch file descriptors for readability and |
|||
writability, similar to the purpose of poll(2). |
|||
|
|||
The purpose of poll handles is to enable integrating external libraries that |
|||
rely on the event loop to signal it about the socket status changes, like |
|||
c-ares or libssh2. Using uv_poll_t for any other purpose is not recommended; |
|||
:c:type:`uv_tcp_t`, :c:type:`uv_udp_t`, etc. provide an implementation that is faster and |
|||
more scalable than what can be achieved with :c:type:`uv_poll_t`, especially on |
|||
Windows. |
|||
|
|||
It is possible that poll handles occasionally signal that a file descriptor is |
|||
readable or writable even when it isn't. The user should therefore always |
|||
be prepared to handle EAGAIN or equivalent when it attempts to read from or |
|||
write to the fd. |
|||
|
|||
It is not okay to have multiple active poll handles for the same socket, this |
|||
can cause libuv to busyloop or otherwise malfunction. |
|||
|
|||
The user should not close a file descriptor while it is being polled by an |
|||
active poll handle. This can cause the handle to report an error, |
|||
but it might also start polling another socket. However the fd can be safely |
|||
closed immediately after a call to :c:func:`uv_poll_stop` or :c:func:`uv_close`. |
|||
|
|||
.. note:: |
|||
On windows only sockets can be polled with poll handles. On Unix any file |
|||
descriptor that would be accepted by poll(2) can be used. |
|||
|
|||
|
|||
Data types |
|||
---------- |
|||
|
|||
.. c:type:: uv_poll_t |
|||
|
|||
Poll handle type. |
|||
|
|||
.. c:type:: void (*uv_poll_cb)(uv_poll_t* handle, int status, int events) |
|||
|
|||
Type definition for callback passed to :c:func:`uv_poll_start`. |
|||
|
|||
.. c:type:: uv_poll_event |
|||
|
|||
Poll event types |
|||
|
|||
:: |
|||
|
|||
enum uv_poll_event { |
|||
UV_READABLE = 1, |
|||
UV_WRITABLE = 2 |
|||
}; |
|||
|
|||
|
|||
Public members |
|||
^^^^^^^^^^^^^^ |
|||
|
|||
N/A |
|||
|
|||
.. seealso:: The :c:type:`uv_handle_t` members also apply. |
|||
|
|||
|
|||
API |
|||
--- |
|||
|
|||
.. c:function:: int uv_poll_init(uv_loop_t* loop, uv_poll_t* handle, int fd) |
|||
|
|||
Initialize the handle using a file descriptor. |
|||
|
|||
.. c:function:: int uv_poll_init_socket(uv_loop_t* loop, uv_poll_t* handle, uv_os_sock_t socket) |
|||
|
|||
Initialize the handle using a socket descriptor. On Unix this is identical |
|||
to :c:func:`uv_poll_init`. On windows it takes a SOCKET handle. |
|||
|
|||
.. c:function:: int uv_poll_start(uv_poll_t* handle, int events, uv_poll_cb cb) |
|||
|
|||
Starts polling the file descriptor. `events` is a bitmask consisting made up |
|||
of UV_READABLE and UV_WRITABLE. As soon as an event is detected the callback |
|||
will be called with `status` set to 0, and the detected events set on the |
|||
`events` field. |
|||
|
|||
If an error happens while polling, `status` will be < 0 and corresponds |
|||
with one of the UV_E* error codes (see :ref:`errors`). The user should |
|||
not close the socket while the handle is active. If the user does that |
|||
anyway, the callback *may* be called reporting an error status, but this |
|||
is **not** guaranteed. |
|||
|
|||
.. note:: |
|||
Calling :c:func:`uv_poll_start` on a handle that is already active is fine. Doing so |
|||
will update the events mask that is being watched for. |
|||
|
|||
.. c:function:: int uv_poll_stop(uv_poll_t* poll) |
|||
|
|||
Stop polling the file descriptor, the callback will no longer be called. |
|||
|
|||
.. seealso:: The :c:type:`uv_handle_t` API functions also apply. |
|||
@ -0,0 +1,46 @@ |
|||
|
|||
.. _prepare: |
|||
|
|||
:c:type:`uv_prepare_t` --- Prepare handle |
|||
========================================= |
|||
|
|||
Prepare handles will run the given callback once per loop iteration, right |
|||
before polling for i/o. |
|||
|
|||
|
|||
Data types |
|||
---------- |
|||
|
|||
.. c:type:: uv_prepare_t |
|||
|
|||
Prepare handle type. |
|||
|
|||
.. c:type:: void (*uv_prepare_cb)(uv_prepare_t* handle) |
|||
|
|||
Type definition for callback passed to :c:func:`uv_prepare_start`. |
|||
|
|||
|
|||
Public members |
|||
^^^^^^^^^^^^^^ |
|||
|
|||
N/A |
|||
|
|||
.. seealso:: The :c:type:`uv_handle_t` members also apply. |
|||
|
|||
|
|||
API |
|||
--- |
|||
|
|||
.. c:function:: int uv_prepare_init(uv_loop_t* loop, uv_prepare_t* prepare) |
|||
|
|||
Initialize the handle. |
|||
|
|||
.. c:function:: int uv_prepare_start(uv_prepare_t* prepare, uv_prepare_cb cb) |
|||
|
|||
Start the handle with the given callback. |
|||
|
|||
.. c:function:: int uv_prepare_stop(uv_prepare_t* prepare) |
|||
|
|||
Stop the handle, the callback will no longer be called. |
|||
|
|||
.. seealso:: The :c:type:`uv_handle_t` API functions also apply. |
|||
@ -0,0 +1,215 @@ |
|||
|
|||
.. _process: |
|||
|
|||
:c:type:`uv_process_t` --- Process handle |
|||
========================================= |
|||
|
|||
Process handles will spawn a new process and allow the user to control it and |
|||
establish communication channels with it using streams. |
|||
|
|||
|
|||
Data types |
|||
---------- |
|||
|
|||
.. c:type:: uv_process_t |
|||
|
|||
Process handle type. |
|||
|
|||
.. c:type:: uv_process_options_t |
|||
|
|||
Options for spawning the process (passed to :c:func:`uv_spawn`. |
|||
|
|||
:: |
|||
|
|||
typedef struct uv_process_options_s { |
|||
uv_exit_cb exit_cb; |
|||
const char* file; |
|||
char** args; |
|||
char** env; |
|||
const char* cwd; |
|||
unsigned int flags; |
|||
int stdio_count; |
|||
uv_stdio_container_t* stdio; |
|||
uv_uid_t uid; |
|||
uv_gid_t gid; |
|||
} uv_process_options_t; |
|||
|
|||
.. c:type:: void (*uv_exit_cb)(uv_process_t*, int64_t exit_status, int term_signal) |
|||
|
|||
Type definition for callback passed in :c:type:`uv_process_options_t` which |
|||
will indicate the exit status and the signal that caused the process to |
|||
terminate, if any. |
|||
|
|||
.. c:type:: uv_process_flags |
|||
|
|||
Flags to be set on the flags field of :c:type:`uv_process_options_t`. |
|||
|
|||
:: |
|||
|
|||
enum uv_process_flags { |
|||
/* |
|||
* Set the child process' user id. |
|||
*/ |
|||
UV_PROCESS_SETUID = (1 << 0), |
|||
/* |
|||
* Set the child process' group id. |
|||
*/ |
|||
UV_PROCESS_SETGID = (1 << 1), |
|||
/* |
|||
* Do not wrap any arguments in quotes, or perform any other escaping, when |
|||
* converting the argument list into a command line string. This option is |
|||
* only meaningful on Windows systems. On Unix it is silently ignored. |
|||
*/ |
|||
UV_PROCESS_WINDOWS_VERBATIM_ARGUMENTS = (1 << 2), |
|||
/* |
|||
* Spawn the child process in a detached state - this will make it a process |
|||
* group leader, and will effectively enable the child to keep running after |
|||
* the parent exits. Note that the child process will still keep the |
|||
* parent's event loop alive unless the parent process calls uv_unref() on |
|||
* the child's process handle. |
|||
*/ |
|||
UV_PROCESS_DETACHED = (1 << 3), |
|||
/* |
|||
* Hide the subprocess console window that would normally be created. This |
|||
* option is only meaningful on Windows systems. On Unix it is silently |
|||
* ignored. |
|||
*/ |
|||
UV_PROCESS_WINDOWS_HIDE = (1 << 4) |
|||
}; |
|||
|
|||
.. c:type:: uv_stdio_container_t |
|||
|
|||
Container for each stdio handle or fd passed to a child process. |
|||
|
|||
:: |
|||
|
|||
typedef struct uv_stdio_container_s { |
|||
uv_stdio_flags flags; |
|||
union { |
|||
uv_stream_t* stream; |
|||
int fd; |
|||
} data; |
|||
} uv_stdio_container_t; |
|||
|
|||
.. c:type:: uv_stdio_flags |
|||
|
|||
Flags specifying how a stdio should be transmitted to the child process. |
|||
|
|||
:: |
|||
|
|||
typedef enum { |
|||
UV_IGNORE = 0x00, |
|||
UV_CREATE_PIPE = 0x01, |
|||
UV_INHERIT_FD = 0x02, |
|||
UV_INHERIT_STREAM = 0x04, |
|||
/* |
|||
* When UV_CREATE_PIPE is specified, UV_READABLE_PIPE and UV_WRITABLE_PIPE |
|||
* determine the direction of flow, from the child process' perspective. Both |
|||
* flags may be specified to create a duplex data stream. |
|||
*/ |
|||
UV_READABLE_PIPE = 0x10, |
|||
UV_WRITABLE_PIPE = 0x20 |
|||
} uv_stdio_flags; |
|||
|
|||
|
|||
Public members |
|||
^^^^^^^^^^^^^^ |
|||
|
|||
.. c:member:: uv_process_t.pid |
|||
|
|||
The PID of the spawned process. It's set after calling :c:func:`uv_spawn`. |
|||
|
|||
.. note:: |
|||
The :c:type:`uv_handle_t` members also apply. |
|||
|
|||
.. c:member:: uv_process_options_t.exit_cb |
|||
|
|||
Callback called after the process exits. |
|||
|
|||
.. c:member:: uv_process_options_t.file |
|||
|
|||
Path pointing to the program to be executed. |
|||
|
|||
.. c:member:: uv_process_options_t.args |
|||
|
|||
Command line arguments. args[0] should be the path to the program. On |
|||
Windows this uses `CreateProcess` which concatenates the arguments into a |
|||
string this can cause some strange errors. See the |
|||
``UV_PROCESS_WINDOWS_VERBATIM_ARGUMENTS`` flag on :c:type:`uv_process_flags`. |
|||
|
|||
.. c:member:: uv_process_options_t.env |
|||
|
|||
Environment for the new process. If NULL the parents environment is used. |
|||
|
|||
.. c:member:: uv_process_options_t.cwd |
|||
|
|||
Current working directory for the subprocess. |
|||
|
|||
.. c:member:: uv_process_options_t.flags |
|||
|
|||
Various flags that control how :c:func:`uv_spawn` behaves. See |
|||
:c:type:`uv_process_flags`. |
|||
|
|||
.. c:member:: uv_process_options_t.stdio_count |
|||
.. c:member:: uv_process_options_t.stdio |
|||
|
|||
The `stdio` field points to an array of :c:type:`uv_stdio_container_t` |
|||
structs that describe the file descriptors that will be made available to |
|||
the child process. The convention is that stdio[0] points to stdin, |
|||
fd 1 is used for stdout, and fd 2 is stderr. |
|||
|
|||
.. note:: |
|||
On Windows file descriptors greater than 2 are available to the child process only if |
|||
the child processes uses the MSVCRT runtime. |
|||
|
|||
.. c:member:: uv_process_options_t.uid |
|||
.. c:member:: uv_process_options_t.gid |
|||
|
|||
Libuv can change the child process' user/group id. This happens only when |
|||
the appropriate bits are set in the flags fields. |
|||
|
|||
.. note:: |
|||
This is not supported on Windows, :c:func:`uv_spawn` will fail and set the error |
|||
to ``UV_ENOTSUP``. |
|||
|
|||
.. c:member:: uv_stdio_container_t.flags |
|||
|
|||
Flags specifying how the stdio container should be passed to the child. See |
|||
:c:type:`uv_stdio_flags`. |
|||
|
|||
.. c:member:: uv_stdio_container_t.data |
|||
|
|||
Union containing either the stream or fd to be passed on to the child |
|||
process. |
|||
|
|||
|
|||
API |
|||
--- |
|||
|
|||
.. c:function:: void uv_disable_stdio_inheritance(void) |
|||
|
|||
Disables inheritance for file descriptors / handles that this process |
|||
inherited from its parent. The effect is that child processes spawned by |
|||
this process don't accidentally inherit these handles. |
|||
|
|||
It is recommended to call this function as early in your program as possible, |
|||
before the inherited file descriptors can be closed or duplicated. |
|||
|
|||
.. note:: |
|||
This function works on a best-effort basis: there is no guarantee that libuv can discover |
|||
all file descriptors that were inherited. In general it does a better job on Windows than |
|||
it does on Unix. |
|||
|
|||
.. c:function:: int uv_spawn(uv_loop_t* loop, uv_process_t* handle, const uv_process_options_t* options) |
|||
|
|||
Initializes the process handle and starts the process. If the process is |
|||
successfully spawned, this function will return 0. Otherwise, the |
|||
negative error code corresponding to the reason it couldn't spawn is |
|||
returned. |
|||
|
|||
Possible reasons for failing to spawn would include (but not be limited to) |
|||
the file to execute not existing, not having permissions to use the setuid or |
|||
setgid specified, or not having enough memory to allocate for the new |
|||
process. |
|||
|
|||
.. seealso:: The :c:type:`uv_handle_t` API functions also apply. |
|||
@ -0,0 +1,82 @@ |
|||
|
|||
.. _request: |
|||
|
|||
:c:type:`uv_req_t` --- Base request |
|||
=================================== |
|||
|
|||
`uv_req_t` is the base type for all libuv request types. |
|||
|
|||
Strcutures are aligned so that any libuv request can be cast to `uv_req_t`. |
|||
All API functions defined here work with any request type. |
|||
|
|||
|
|||
Data types |
|||
---------- |
|||
|
|||
.. c:type:: uv_req_t |
|||
|
|||
The base libuv request structure. |
|||
|
|||
.. c:type:: uv_any_req |
|||
|
|||
Union of all request types. |
|||
|
|||
|
|||
Public members |
|||
^^^^^^^^^^^^^^ |
|||
|
|||
.. c:member:: void* uv_request_t.data |
|||
|
|||
Space for user-defined arbitrary data. libuv does not use this field. |
|||
|
|||
.. c:member:: uv_req_type uv_req_t.type |
|||
|
|||
Indicated the type of request. Readonly. |
|||
|
|||
:: |
|||
|
|||
typedef enum { |
|||
UV_UNKNOWN_REQ = 0, |
|||
UV_REQ, |
|||
UV_CONNECT, |
|||
UV_WRITE, |
|||
UV_SHUTDOWN, |
|||
UV_UDP_SEND, |
|||
UV_FS, |
|||
UV_WORK, |
|||
UV_GETADDRINFO, |
|||
UV_GETNAMEINFO, |
|||
UV_REQ_TYPE_PRIVATE, |
|||
UV_REQ_TYPE_MAX, |
|||
} uv_req_type; |
|||
|
|||
|
|||
API |
|||
--- |
|||
|
|||
.. c:function:: int uv_cancel(uv_req_t* req) |
|||
|
|||
Cancel a pending request. Fails if the request is executing or has finished |
|||
executing. |
|||
|
|||
Returns 0 on success, or an error code < 0 on failure. |
|||
|
|||
Only cancellation of :c:type:`uv_fs_t`, :c:type:`uv_getaddrinfo_t`, |
|||
:c:type:`uv_getnameinfo_t` and :c:type:`uv_work_t` requests is |
|||
currently supported. |
|||
|
|||
Cancelled requests have their callbacks invoked some time in the future. |
|||
It's **not** safe to free the memory associated with the request until the |
|||
callback is called. |
|||
|
|||
Here is how cancellation is reported to the callback: |
|||
|
|||
* A :c:type:`uv_fs_t` request has its req->result field set to `UV_ECANCELED`. |
|||
|
|||
* A :c:type:`uv_work_t`, :c:type:`uv_getaddrinfo_t` or c:type:`uv_getnameinfo_t` |
|||
request has its callback invoked with status == `UV_ECANCELED`. |
|||
|
|||
.. c:function:: size_t uv_req_size(uv_req_type type) |
|||
|
|||
Returns the size of the given request type. Useful for FFI binding writers |
|||
who don't want to know the structure layout. |
|||
@ -0,0 +1,77 @@ |
|||
|
|||
.. _signal: |
|||
|
|||
:c:type:`uv_signal_t` --- Signal handle |
|||
======================================= |
|||
|
|||
Signal handles implement Unix style signal handling on a per-event loop bases. |
|||
|
|||
Reception of some signals is emulated on Windows: |
|||
|
|||
* SIGINT is normally delivered when the user presses CTRL+C. However, like |
|||
on Unix, it is not generated when terminal raw mode is enabled. |
|||
|
|||
* SIGBREAK is delivered when the user pressed CTRL + BREAK. |
|||
|
|||
* SIGHUP is generated when the user closes the console window. On SIGHUP the |
|||
program is given approximately 10 seconds to perform cleanup. After that |
|||
Windows will unconditionally terminate it. |
|||
|
|||
* SIGWINCH is raised whenever libuv detects that the console has been |
|||
resized. SIGWINCH is emulated by libuv when the program uses a :c:type:`uv_tty_t` |
|||
handle to write to the console. SIGWINCH may not always be delivered in a |
|||
timely manner; libuv will only detect size changes when the cursor is |
|||
being moved. When a readable :c:type:`uv_tty_t` handle is used in raw mode, |
|||
resizing the console buffer will also trigger a SIGWINCH signal. |
|||
|
|||
Watchers for other signals can be successfully created, but these signals |
|||
are never received. These signals are: `SIGILL`, `SIGABRT`, `SIGFPE`, `SIGSEGV`, |
|||
`SIGTERM` and `SIGKILL.` |
|||
|
|||
Calls to raise() or abort() to programmatically raise a signal are |
|||
not detected by libuv; these will not trigger a signal watcher. |
|||
|
|||
.. note:: |
|||
On Linux SIGRT0 and SIGRT1 (signals 32 and 33) are used by the NPTL pthreads library to |
|||
manage threads. Installing watchers for those signals will lead to unpredictable behavior |
|||
and is strongly discouraged. Future versions of libuv may simply reject them. |
|||
|
|||
|
|||
Data types |
|||
---------- |
|||
|
|||
.. c:type:: uv_signal_t |
|||
|
|||
Signal handle type. |
|||
|
|||
.. c:type:: void (*uv_signal_cb)(uv_signal_t* handle, int signum) |
|||
|
|||
Type definition for callback passed to :c:func:`uv_signal_start`. |
|||
|
|||
|
|||
Public members |
|||
^^^^^^^^^^^^^^ |
|||
|
|||
.. c:member:: int uv_signal_t.signum |
|||
|
|||
Signal being monitored by this handle. Readonly. |
|||
|
|||
.. seealso:: The :c:type:`uv_handle_t` members also apply. |
|||
|
|||
|
|||
API |
|||
--- |
|||
|
|||
.. c:function:: int uv_signal_init(uv_loop_t*, uv_signal_t* signal) |
|||
|
|||
Initialize the handle. |
|||
|
|||
.. c:function:: int uv_signal_start(uv_signal_t* signal, uv_signal_cb cb, int signum) |
|||
|
|||
Start the handle with the given callback, watching for the given signal. |
|||
|
|||
.. c:function:: int uv_signal_stop(uv_signal_t* signal) |
|||
|
|||
Stop the handle, the callback will no longer be called. |
|||
|
|||
.. seealso:: The :c:type:`uv_handle_t` API functions also apply. |
|||
|
After Width: | Height: | Size: 202 KiB |
|
After Width: | Height: | Size: 19 KiB |
|
After Width: | Height: | Size: 12 KiB |
Binary file not shown.
@ -0,0 +1,8 @@ |
|||
<?xml version="1.0" encoding="UTF-8"?> |
|||
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> |
|||
<plist version="1.0"> |
|||
<array> |
|||
<string>Template: White (2014-02-28 09:41)</string> |
|||
<string>M6.2.2-1878-1</string> |
|||
</array> |
|||
</plist> |
|||
@ -0,0 +1 @@ |
|||
F69E9CD9-EEF1-4223-9DA4-A1EA7FE112BA |
|||
Binary file not shown.
|
After Width: | Height: | Size: 1.4 KiB |
|
After Width: | Height: | Size: 7.9 KiB |
|
After Width: | Height: | Size: 105 KiB |
|
After Width: | Height: | Size: 15 KiB |
|
After Width: | Height: | Size: 33 KiB |
|
After Width: | Height: | Size: 79 KiB |
@ -0,0 +1,189 @@ |
|||
|
|||
.. _stream: |
|||
|
|||
:c:type:`uv_stream_t` --- Stream handle |
|||
======================================= |
|||
|
|||
Stream handles provide an abstraction of a duplex communication channel. |
|||
:c:type:`uv_stream_t` is an abstract type, libuv provides 3 stream implementations |
|||
in the for of :c:type:`uv_tcp_t`, :c:type:`uv_pipe_t` and :c:type:`uv_tty_t`. |
|||
|
|||
|
|||
Data types |
|||
---------- |
|||
|
|||
.. c:type:: uv_stream_t |
|||
|
|||
Stream handle type. |
|||
|
|||
.. c:type:: void (*uv_read_cb)(uv_stream_t* stream, ssize_t nread, const uv_buf_t* buf) |
|||
|
|||
Callback called when data was read on a stream. |
|||
|
|||
`nread` is > 0 if there is data available, 0 if libuv is done reading for |
|||
now, or < 0 on error. |
|||
|
|||
The callee is responsible for stopping closing the stream when an error happens |
|||
by calling :c:func:`uv_read_stop` or :c:func:`uv_close`. Trying to read |
|||
from the stream again is undefined. |
|||
|
|||
The callee is responsible for freeing the buffer, libuv does not reuse it. |
|||
The buffer may be a null buffer (where buf->base=NULL and buf->len=0) on |
|||
error. |
|||
|
|||
.. c:type:: void (*uv_write_cb)(uv_write_t* req, int status) |
|||
|
|||
Callback called after data was written on a stream. `status` will be 0 in |
|||
case of success, < 0 otherwise. |
|||
|
|||
.. c:type:: void (*uv_connect_cb)(uv_connect_t* req, int status) |
|||
|
|||
Callback called after a connection started by :c:func:`uv_connect` is done. |
|||
`status` will be 0 in case of success, < 0 otherwise. |
|||
|
|||
.. c:type:: void (*uv_shutdown_cb)(uv_shutdown_t* req, int status) |
|||
|
|||
Callback called after s shutdown request has been completed. `status` will |
|||
be 0 in case of success, < 0 otherwise. |
|||
|
|||
.. c:type:: void (*uv_connection_cb)(uv_stream_t* server, int status) |
|||
|
|||
Callback called when a stream server has received an incoming connection. |
|||
The user can accept the connection by calling :c:func:`uv_accept`. |
|||
`status` will de 0 in case of success, < 0 otherwise. |
|||
|
|||
|
|||
Public members |
|||
^^^^^^^^^^^^^^ |
|||
|
|||
.. c:member:: size_t uv_stream_t.write_queue_size |
|||
|
|||
Contains the amount of queued bytes waiting to be sent. Readonly. |
|||
|
|||
.. seealso:: The :c:type:`uv_handle_t` members also apply. |
|||
|
|||
|
|||
API |
|||
--- |
|||
|
|||
.. c:function:: int uv_shutdown(uv_shutdown_t* req, uv_stream_t* handle, uv_shutdown_cb cb) |
|||
|
|||
Shutdown the outgoing (write) side of a duplex stream. It waits for pending |
|||
write requests to complete. The `handle` should refer to a initialized stream. |
|||
`req` should be an uninitialized shutdown request struct. The `cb` is called |
|||
after shutdown is complete. |
|||
|
|||
.. c:function:: int uv_listen(uv_stream_t* stream, int backlog, uv_connection_cb cb) |
|||
|
|||
Start listening for incoming connections. `backlog` indicates the number of |
|||
connections the kernel might queue, same as ``listen(2)``. When a new |
|||
incoming connection is received the :c:type:`uv_connection_cb` callback is |
|||
called. |
|||
|
|||
.. c:function:: int uv_accept(uv_stream_t* server, uv_stream_t* client) |
|||
|
|||
This call is used in conjunction with :c:func:`uv_listen` to accept incoming |
|||
connections. Call this function after receiving a :c:type:`uv_connection_cb` |
|||
to accept the connection. Before calling this function the client handle must |
|||
be initialized. < 0 return value indicates an error. |
|||
|
|||
When the :c:type:`uv_connection_cb` callback is called it is guaranteed that |
|||
this function will complete successfully the first time. If you attempt to use |
|||
it more than once, it may fail. It is suggested to only call this function once |
|||
per :c:type:`uv_connection_cb` call. |
|||
|
|||
.. note:: |
|||
`server` and `client` must be handles running on the same loop. |
|||
|
|||
.. c:function:: int uv_read_start(uv_stream_t*, uv_alloc_cb alloc_cb, uv_read_cb read_cb) |
|||
|
|||
Read data from an incoming stream. The callback will be made several |
|||
times until there is no more data to read or :c:func:`uv_read_stop` is called. |
|||
When we've reached EOF `nread` will be set to ``UV_EOF``. |
|||
|
|||
When `nread` < 0, the `buf` parameter might not point to a valid buffer; |
|||
in that case `buf.len` and `buf.base` are both set to 0. |
|||
|
|||
.. note:: |
|||
`nread` might also be 0, which does *not* indicate an error or EOF, it happens when |
|||
libuv requested a buffer through the alloc callback but then decided that it didn't |
|||
need that buffer. |
|||
|
|||
.. c:function:: int uv_read_stop(uv_stream_t*) |
|||
|
|||
Stop reading data from the stream. The :c:type:`uv_read_cb` callback will |
|||
no longer be called. |
|||
|
|||
.. c:function:: int uv_write(uv_write_t* req, uv_stream_t* handle, const uv_buf_t bufs[], unsigned int nbufs, uv_write_cb cb) |
|||
|
|||
Write data to stream. Buffers are written in order. Example: |
|||
|
|||
:: |
|||
|
|||
uv_buf_t a[] = { |
|||
{ .base = "1", .len = 1 }, |
|||
{ .base = "2", .len = 1 } |
|||
}; |
|||
|
|||
uv_buf_t b[] = { |
|||
{ .base = "3", .len = 1 }, |
|||
{ .base = "4", .len = 1 } |
|||
}; |
|||
|
|||
uv_write_t req1; |
|||
uv_write_t req2; |
|||
|
|||
/* writes "1234" */ |
|||
uv_write(&req1, stream, a, 2); |
|||
uv_write(&req2, stream, b, 2); |
|||
|
|||
.. c:function:: int uv_write2(uv_write_t* req, uv_stream_t* handle, const uv_buf_t bufs[], unsigned int nbufs, uv_stream_t* send_handle, uv_write_cb cb) |
|||
|
|||
Extended write function for sending handles over a pipe. The pipe must be |
|||
initialized with `ipc` == 1. |
|||
|
|||
.. note:: |
|||
`send_handle` must be a TCP socket or pipe, which is a server or a connection (listening |
|||
or connected state). Bound sockets or pipes will be assumed to be servers. |
|||
|
|||
.. c:function:: int uv_try_write(uv_stream_t* handle, const uv_buf_t bufs[], unsigned int nbufs) |
|||
|
|||
Same as :c:func:`uv_write`, but won't queue a write request if it can't be |
|||
completed immediately. |
|||
|
|||
Will return either: |
|||
|
|||
* > 0: number of bytes written (can be less than the supplied buffer size). |
|||
* < 0: negative error code (``UV_EAGAIN`` is returned if no data can be sent |
|||
immediately). |
|||
|
|||
.. c:function:: int uv_is_readable(const uv_stream_t* handle) |
|||
|
|||
Returns 1 if the stream is readable, 0 otherwise. |
|||
|
|||
.. c:function:: int uv_is_writable(const uv_stream_t* handle) |
|||
|
|||
Returns 1 if the stream is writable, 0 otherwise. |
|||
|
|||
.. c:function:: int uv_stream_set_blocking(uv_stream_t* handle, int blocking) |
|||
|
|||
Enable or disable blocking mode for a stream. |
|||
|
|||
When blocking mode is enabled all writes complete synchronously. The |
|||
interface remains unchanged otherwise, e.g. completion or failure of the |
|||
operation will still be reported through a callback which is made |
|||
asychronously. |
|||
|
|||
.. warning:: |
|||
Relying too much on this API is not recommended. It is likely to change |
|||
significantly in the future. |
|||
|
|||
Currently this only works on Windows and only for |
|||
:c:type:`uv_pipe_t` handles. |
|||
|
|||
Also libuv currently makes no ordering guarantee when the blocking mode |
|||
is changed after write requests have already been submitted. Therefore it is |
|||
recommended to set the blocking mode immediately after opening or creating |
|||
the stream. |
|||
|
|||
.. seealso:: The :c:type:`uv_handle_t` API functions also apply. |
|||
@ -0,0 +1,97 @@ |
|||
|
|||
.. _tcp: |
|||
|
|||
:c:type:`uv_tcp_t` --- TCP handle |
|||
================================= |
|||
|
|||
TCP handles are used to represent both TCP streams and servers. |
|||
|
|||
:c:type:`uv_tcp_t` is a 'subclass' of :c:type:`uv_stream_t`. |
|||
|
|||
|
|||
Data types |
|||
---------- |
|||
|
|||
.. c:type:: uv_tcp_t |
|||
|
|||
TCP handle type. |
|||
|
|||
|
|||
Public members |
|||
^^^^^^^^^^^^^^ |
|||
|
|||
N/A |
|||
|
|||
.. seealso:: The :c:type:`uv_stream_t` members also apply. |
|||
|
|||
|
|||
API |
|||
--- |
|||
|
|||
.. c:function:: int uv_tcp_init(uv_loop_t*, uv_tcp_t* handle) |
|||
|
|||
Initialize the handle. |
|||
|
|||
.. c:function:: int uv_tcp_open(uv_tcp_t* handle, uv_os_sock_t sock) |
|||
|
|||
Open an existing file descriptor or SOCKET as a TCP handle. |
|||
|
|||
.. note:: |
|||
The user is responsible for setting the file descriptor in |
|||
non-blocking mode. |
|||
|
|||
.. c:function:: int uv_tcp_nodelay(uv_tcp_t* handle, int enable) |
|||
|
|||
Enable / disable Nagle's algorithm. |
|||
|
|||
.. c:function:: int uv_tcp_keepalive(uv_tcp_t* handle, int enable, unsigned int delay) |
|||
|
|||
Enable / disable TCP keep-alive. `delay` is the initial delay in seconds, |
|||
ignored when `enable` is zero. |
|||
|
|||
.. c:function:: int uv_tcp_simultaneous_accepts(uv_tcp_t* handle, int enable) |
|||
|
|||
Enable / disable simultaneous asynchronous accept requests that are |
|||
queued by the operating system when listening for new TCP connections. |
|||
|
|||
This setting is used to tune a TCP server for the desired performance. |
|||
Having simultaneous accepts can significantly improve the rate of accepting |
|||
connections (which is why it is enabled by default) but may lead to uneven |
|||
load distribution in multi-process setups. |
|||
|
|||
.. c:function:: int uv_tcp_bind(uv_tcp_t* handle, const struct sockaddr* addr, unsigned int flags) |
|||
|
|||
Bind the handle to an address and port. `addr` should point to an |
|||
initialized ``struct sockaddr_in`` or ``struct sockaddr_in6``. |
|||
|
|||
When the port is already taken, you can expect to see an ``UV_EADDRINUSE`` |
|||
error from either :c:func:`uv_tcp_bind`, :c:func:`uv_listen` or |
|||
:c:func:`uv_tcp_connect`. That is, a successful call to this function does |
|||
not guarantee that the call to :c:func:`uv_listen` or :c:func:`uv_tcp_connect` |
|||
will succeed as well. |
|||
|
|||
`flags` con contain ``UV_TCP_IPV6ONLY``, in which case dual-stack support |
|||
is disabled and only IPv6 is used. |
|||
|
|||
.. c:function:: int uv_tcp_getsockname(const uv_tcp_t* handle, struct sockaddr* name, int* namelen) |
|||
|
|||
Get the current address to which the handle is bound. `addr` must point to |
|||
a valid and big enough chunk of memory, ``struct sockaddr_storage`` is |
|||
recommended for IPv4 and IPv6 support. |
|||
|
|||
.. c:function:: int uv_tcp_getpeername(const uv_tcp_t* handle, struct sockaddr* name, int* namelen) |
|||
|
|||
Get the address of the peer connected to the handle. `addr` must point to |
|||
a valid and big enough chunk of memory, ``struct sockaddr_storage`` is |
|||
recommended for IPv4 and IPv6 support. |
|||
|
|||
.. c:function:: int uv_tcp_connect(uv_connect_t* req, uv_tcp_t* handle, const struct sockaddr* addr, uv_connect_cb cb) |
|||
|
|||
Establish an IPv4 or IPv6 TCP connection. Provide an initialized TCP handle |
|||
and an uninitialized :c:type:`uv_connect_t`. `addr` should point to an |
|||
initialized ``struct sockaddr_in`` or ``struct sockaddr_in6``. |
|||
|
|||
The callback is made when the connection has been established or when a |
|||
connection error happened. |
|||
|
|||
.. seealso:: The :c:type:`uv_stream_t` API functions also apply. |
|||
@ -0,0 +1,156 @@ |
|||
|
|||
.. _threading: |
|||
|
|||
Threading and synchronization utilities |
|||
======================================= |
|||
|
|||
libuv provides cross-platform implementations for multiple threading and |
|||
synchronization primitives. The API largely follows the pthreads API. |
|||
|
|||
|
|||
Data types |
|||
---------- |
|||
|
|||
.. c:type:: uv_thread_t |
|||
|
|||
Thread data type. |
|||
|
|||
.. c:type:: void (*uv_thread_cb)(void* arg) |
|||
|
|||
Callback that is invoked to initialize thread execution. `arg` is the same |
|||
value that was passed to :c:func:`uv_thread_create`. |
|||
|
|||
.. c:type:: uv_key_t |
|||
|
|||
Thread-local key data type. |
|||
|
|||
.. c:type:: uv_once_t |
|||
|
|||
Once-only initializer data type. |
|||
|
|||
.. c:type:: uv_mutex_t |
|||
|
|||
Mutex data type. |
|||
|
|||
.. c:type:: uv_rwlock_t |
|||
|
|||
Read-write lock data type. |
|||
|
|||
.. c:type:: uv_sem_t |
|||
|
|||
Semaphore data type. |
|||
|
|||
.. c:type:: uv_cond_t |
|||
|
|||
Condition data type. |
|||
|
|||
.. c:type:: uv_barrier_t |
|||
|
|||
Barrier data type. |
|||
|
|||
|
|||
API |
|||
--- |
|||
|
|||
Threads |
|||
^^^^^^^ |
|||
|
|||
.. c:function:: int uv_thread_create(uv_thread_t* tid, uv_thread_cb entry, void* arg) |
|||
.. c:function:: unsigned long uv_thread_self(void) |
|||
.. c:function:: int uv_thread_join(uv_thread_t *tid) |
|||
|
|||
Thread-local storage |
|||
^^^^^^^^^^^^^^^^^^^^ |
|||
|
|||
.. note:: |
|||
The total thread-local storage size may be limited. That is, it may not be possible to |
|||
create many TLS keys. |
|||
|
|||
.. c:function:: int uv_key_create(uv_key_t* key) |
|||
.. c:function:: void uv_key_delete(uv_key_t* key) |
|||
.. c:function:: void* uv_key_get(uv_key_t* key) |
|||
.. c:function:: void uv_key_set(uv_key_t* key, void* value) |
|||
|
|||
Once-only initialization |
|||
^^^^^^^^^^^^^^^^^^^^^^^^ |
|||
|
|||
Runs a function once and only once. Concurrent calls to :c:func:`uv_once` with the |
|||
same guard will block all callers except one (it's unspecified which one). |
|||
The guard should be initialized statically with the UV_ONCE_INIT macro. |
|||
|
|||
.. c:function:: void uv_once(uv_once_t* guard, void (*callback)(void)) |
|||
|
|||
Mutex locks |
|||
^^^^^^^^^^^ |
|||
|
|||
Functions return 0 on success or an error code < 0 (unless the |
|||
return type is void, of course). |
|||
|
|||
.. c:function:: int uv_mutex_init(uv_mutex_t* handle) |
|||
.. c:function:: void uv_mutex_destroy(uv_mutex_t* handle) |
|||
.. c:function:: void uv_mutex_lock(uv_mutex_t* handle) |
|||
.. c:function:: int uv_mutex_trylock(uv_mutex_t* handle) |
|||
.. c:function:: void uv_mutex_unlock(uv_mutex_t* handle) |
|||
|
|||
Read-write locks |
|||
^^^^^^^^^^^^^^^^ |
|||
|
|||
Functions return 0 on success or an error code < 0 (unless the |
|||
return type is void, of course). |
|||
|
|||
.. c:function:: int uv_rwlock_init(uv_rwlock_t* rwlock) |
|||
.. c:function:: void uv_rwlock_destroy(uv_rwlock_t* rwlock) |
|||
.. c:function:: void uv_rwlock_rdlock(uv_rwlock_t* rwlock) |
|||
.. c:function:: int uv_rwlock_tryrdlock(uv_rwlock_t* rwlock) |
|||
.. c:function:: void uv_rwlock_rdunlock(uv_rwlock_t* rwlock) |
|||
.. c:function:: void uv_rwlock_wrlock(uv_rwlock_t* rwlock) |
|||
.. c:function:: int uv_rwlock_trywrlock(uv_rwlock_t* rwlock) |
|||
.. c:function:: void uv_rwlock_wrunlock(uv_rwlock_t* rwlock) |
|||
|
|||
Semaphores |
|||
^^^^^^^^^^ |
|||
|
|||
Functions return 0 on success or an error code < 0 (unless the |
|||
return type is void, of course). |
|||
|
|||
.. c:function:: int uv_sem_init(uv_sem_t* sem, unsigned int value) |
|||
.. c:function:: void uv_sem_destroy(uv_sem_t* sem) |
|||
.. c:function:: void uv_sem_post(uv_sem_t* sem) |
|||
.. c:function:: void uv_sem_wait(uv_sem_t* sem) |
|||
.. c:function:: int uv_sem_trywait(uv_sem_t* sem) |
|||
|
|||
Conditions |
|||
^^^^^^^^^^ |
|||
|
|||
Functions return 0 on success or an error code < 0 (unless the |
|||
return type is void, of course). |
|||
|
|||
.. note:: |
|||
Callers should be prepared to deal with spurious wakeups on :c:func:`uv_cond_wait` and |
|||
:c:func:`uv_cond_timedwait`. |
|||
|
|||
.. c:function:: int uv_cond_init(uv_cond_t* cond) |
|||
.. c:function:: void uv_cond_destroy(uv_cond_t* cond) |
|||
.. c:function:: void uv_cond_signal(uv_cond_t* cond) |
|||
.. c:function:: void uv_cond_broadcast(uv_cond_t* cond) |
|||
.. c:function:: void uv_cond_wait(uv_cond_t* cond, uv_mutex_t* mutex) |
|||
.. c:function:: int uv_cond_timedwait(uv_cond_t* cond, uv_mutex_t* mutex, uint64_t timeout) |
|||
|
|||
Barriers |
|||
^^^^^^^^ |
|||
|
|||
Functions return 0 on success or an error code < 0 (unless the |
|||
return type is void, of course). |
|||
|
|||
.. note:: |
|||
:c:func:`uv_barrier_wait` returns a value > 0 to an arbitrarily chosen "serializer" thread |
|||
to facilitate cleanup, i.e. |
|||
|
|||
:: |
|||
|
|||
if (uv_barrier_wait(&barrier) > 0) |
|||
uv_barrier_destroy(&barrier); |
|||
|
|||
.. c:function:: int uv_barrier_init(uv_barrier_t* barrier, unsigned int count) |
|||
.. c:function:: void uv_barrier_destroy(uv_barrier_t* barrier) |
|||
.. c:function:: int uv_barrier_wait(uv_barrier_t* barrier) |
|||
@ -0,0 +1,59 @@ |
|||
|
|||
.. _threadpool: |
|||
|
|||
Thread pool work scheduling |
|||
=========================== |
|||
|
|||
libuv provides a threadpool which can be used to run user code and get notified |
|||
in the loop thread. This thread pool is internally used to run al filesystem |
|||
operations, as well as getaddrinfo and getnameinfo requests. |
|||
|
|||
Its default size is 4, but it can be changed at startup time by setting the |
|||
``UV_THREADPOOL_SIZE`` environment variable to any value (the absolute maximum |
|||
is 128). |
|||
|
|||
The threadpool is global and shared across all event loops. |
|||
|
|||
|
|||
Data types |
|||
---------- |
|||
|
|||
.. c:type:: uv_work_t |
|||
|
|||
Work request type. |
|||
|
|||
.. c:type:: void (*uv_work_cb)(uv_work_t* req) |
|||
|
|||
Callback passed to :c:func:`uv_queue_work` which will be run on the thread |
|||
pool. |
|||
|
|||
.. c:type:: void (*uv_after_work_cb)(uv_work_t* req, int status) |
|||
|
|||
Callback passed to :c:func:`uv_queue_work` which will be called on the loop |
|||
thread after the work on the threadpool has been completed. If the work |
|||
was cancelled using :c:func:`uv_cancel` `status` will be ``UV_ECANCELED``. |
|||
|
|||
|
|||
Public members |
|||
^^^^^^^^^^^^^^ |
|||
|
|||
.. c:member:: uv_loop_t* uv_work_t.loop |
|||
|
|||
Loop that started this request and where completion will be reported. |
|||
Readonly. |
|||
|
|||
.. seealso:: The :c:type:`uv_req_t` members also apply. |
|||
|
|||
|
|||
API |
|||
--- |
|||
|
|||
.. c:function:: int uv_queue_work(uv_loop_t* loop, uv_work_t* req, uv_work_cb work_cb, uv_after_work_cb after_work_cb) |
|||
|
|||
Initializes a work request which will run the given `work_cb` in a thread |
|||
from the threadpool. Once `work_cb` is completed, `after_work_cb` will be |
|||
called on the loop thread. |
|||
|
|||
This request can be cancelled with :c:func:`uv_cancel`. |
|||
|
|||
.. seealso:: The :c:type:`uv_req_t` API functions also apply. |
|||
@ -0,0 +1,68 @@ |
|||
|
|||
.. _timer: |
|||
|
|||
:c:type:`uv_timer_t` --- Timer handle |
|||
===================================== |
|||
|
|||
Timer handles are used to schedule callbacks to be called in the future. |
|||
|
|||
|
|||
Data types |
|||
---------- |
|||
|
|||
.. c:type:: uv_timer_t |
|||
|
|||
Timer handle type. |
|||
|
|||
.. c:type:: void (*uv_timer_cb)(uv_timer_t* handle) |
|||
|
|||
Type definition for callback passed to :c:func:`uv_timer_start`. |
|||
|
|||
|
|||
Public members |
|||
^^^^^^^^^^^^^^ |
|||
|
|||
N/A |
|||
|
|||
.. seealso:: The :c:type:`uv_handle_t` members also apply. |
|||
|
|||
|
|||
API |
|||
--- |
|||
|
|||
.. c:function:: int uv_timer_init(uv_loop_t* loop, uv_timer_t* handle) |
|||
|
|||
Initialize the handle. |
|||
|
|||
.. c:function:: int uv_timer_start(uv_timer_t* handle, uv_timer_cb cb, uint64_t timeout, uint64_t repeat) |
|||
|
|||
Start the timer. `timeout` and `repeat` are in milliseconds. |
|||
|
|||
If `timeout` is zero, the callback fires on the next event loop iteration. |
|||
If `repeat` is non-zero, the callback fires first after `timeout` |
|||
milliseconds and then repeatedly after `repeat` milliseconds. |
|||
|
|||
.. c:function:: int uv_timer_stop(uv_timer_t* handle) |
|||
|
|||
Stop the timer, the callback will not be called anymore. |
|||
|
|||
.. c:function:: int uv_timer_again(uv_timer_t* handle) |
|||
|
|||
Stop the timer, and if it is repeating restart it using the repeat value |
|||
as the timeout. If the timer has never been started before it returns |
|||
UV_EINVAL. |
|||
|
|||
.. c:function:: void uv_timer_set_repeat(uv_timer_t* handle, uint64_t repeat) |
|||
|
|||
Set the repeat value in milliseconds. |
|||
|
|||
.. note:: |
|||
If the repeat value is set from a timer callback it does not immediately take effect. |
|||
If the timer was non-repeating before, it will have been stopped. If it was repeating, |
|||
then the old repeat value will have been used to schedule the next timeout. |
|||
|
|||
.. c:function:: uint64_t uv_timer_get_repeat(const uv_timer_t* handle) |
|||
|
|||
Get the timer repeat value. |
|||
|
|||
.. seealso:: The :c:type:`uv_handle_t` API functions also apply. |
|||
@ -0,0 +1,63 @@ |
|||
|
|||
.. _tty: |
|||
|
|||
:c:type:`uv_tty_t` --- TTY handle |
|||
================================= |
|||
|
|||
TTY handles represent a stream for the console. |
|||
|
|||
:c:type:`uv_tty_t` is a 'subclass' of :c:type:`uv_stream_t`. |
|||
|
|||
|
|||
Data types |
|||
---------- |
|||
|
|||
.. c:type:: uv_tty_t |
|||
|
|||
TTY handle type. |
|||
|
|||
|
|||
Public members |
|||
^^^^^^^^^^^^^^ |
|||
|
|||
N/A |
|||
|
|||
.. seealso:: The :c:type:`uv_stream_t` members also apply. |
|||
|
|||
|
|||
API |
|||
--- |
|||
|
|||
.. c:function:: int uv_tty_init(uv_loop_t*, uv_tty_t*, uv_file fd, int readable) |
|||
|
|||
Initialize a new TTY stream with the given file descriptor. Usually the |
|||
file descriptor will be: |
|||
|
|||
* 0 = stdin |
|||
* 1 = stdout |
|||
* 2 = stderr |
|||
|
|||
`readable`, specifies if you plan on calling :c:func:`uv_read_start` with |
|||
this stream. stdin is readable, stdout is not. |
|||
|
|||
.. note:: |
|||
TTY streams which are not readable have blocking writes. |
|||
|
|||
.. c:function:: int uv_tty_set_mode(uv_tty_t*, int mode) |
|||
|
|||
Set the TTY mode. 0 for normal, 1 for raw. |
|||
|
|||
.. c:function:: int uv_tty_reset_mode(void) |
|||
|
|||
To be called when the program exits. Resets TTY settings to default |
|||
values for the next process to take over. |
|||
|
|||
This function is async signal-safe on Unix platforms but can fail with error |
|||
code ``UV_EBUSY`` if you call it when execution is inside |
|||
:c:func:`uv_tty_set_mode`. |
|||
|
|||
.. c:function:: int uv_tty_get_winsize(uv_tty_t*, int* width, int* height) |
|||
|
|||
Gets the current Window size. On success it returns 0. |
|||
|
|||
.. seealso:: The :c:type:`uv_stream_t` API functions also apply. |
|||
@ -0,0 +1,280 @@ |
|||
|
|||
.. _udp: |
|||
|
|||
:c:type:`uv_udp_t` --- UDP handle |
|||
================================= |
|||
|
|||
UDP handles encapsulate UDP communication for both clients and servers. |
|||
|
|||
|
|||
Data types |
|||
---------- |
|||
|
|||
.. c:type:: uv_udp_t |
|||
|
|||
UDP handle type. |
|||
|
|||
.. c:type:: uv_udp_send_t |
|||
|
|||
UDP send request type. |
|||
|
|||
.. c:type:: uv_udp_flags |
|||
|
|||
Flags used in :c:func:`uv_udp_bind` and :c:type:`uv_udp_recv_cb`.. |
|||
|
|||
:: |
|||
|
|||
enum uv_udp_flags { |
|||
/* Disables dual stack mode. */ |
|||
UV_UDP_IPV6ONLY = 1, |
|||
/* |
|||
* Indicates message was truncated because read buffer was too small. The |
|||
* remainder was discarded by the OS. Used in uv_udp_recv_cb. |
|||
*/ |
|||
UV_UDP_PARTIAL = 2, |
|||
/* |
|||
* Indicates if SO_REUSEADDR will be set when binding the handle in |
|||
* uv_udp_bind. |
|||
* This sets the SO_REUSEPORT socket flag on the BSDs and OS X. On other |
|||
* Unix platforms, it sets the SO_REUSEADDR flag. What that means is that |
|||
* multiple threads or processes can bind to the same address without error |
|||
* (provided they all set the flag) but only the last one to bind will receive |
|||
* any traffic, in effect "stealing" the port from the previous listener. |
|||
*/ |
|||
UV_UDP_REUSEADDR = 4 |
|||
}; |
|||
|
|||
.. c:type:: void (*uv_udp_send_cb)(uv_udp_send_t* req, int status) |
|||
|
|||
Type definition for callback passed to :c:func:`uv_udp_send`, which is |
|||
called after the data was sent. |
|||
|
|||
.. c:type:: void (*uv_udp_recv_cb)(uv_udp_t* handle, ssize_t nread, const uv_buf_t* buf, const struct sockaddr* addr, unsigned flags) |
|||
|
|||
Type definition for callback passed to :c:func:`uv_udp_recv_start`, which |
|||
is called when the endpoint receives data. |
|||
|
|||
* `handle`: UDP handle |
|||
* `nread`: Number of bytes that have been received. |
|||
0 if there is no more data to read. You may discard or repurpose |
|||
the read buffer. Note that 0 may also mean that an empty datagram |
|||
was received (in this case `addr` is not NULL). < 0 if a transmission |
|||
error was detected. |
|||
* `buf`: :c:type:`uv_buf_t` with the received data. |
|||
* `addr`: ``struct sockaddr*`` containing the address of the sender. |
|||
Can be NULL. Valid for the duration of the callback only. |
|||
* `flags`: One or more or'ed UV_UDP_* constants. Right now only |
|||
``UV_UDP_PARTIAL`` is used. |
|||
|
|||
.. note:: |
|||
The receive callback will be called with `nread` == 0 and `addr` == NULL when there is |
|||
nothing to read, and with `nread` == 0 and `addr` != NULL when an empty UDP packet is |
|||
received. |
|||
|
|||
.. c:type:: uv_membership |
|||
|
|||
Membership type for a multicast address. |
|||
|
|||
:: |
|||
|
|||
typedef enum { |
|||
UV_LEAVE_GROUP = 0, |
|||
UV_JOIN_GROUP |
|||
} uv_membership; |
|||
|
|||
|
|||
Public members |
|||
^^^^^^^^^^^^^^ |
|||
|
|||
.. c:member:: size_t uv_udp_t.send_queue_size |
|||
|
|||
Number of bytes queued for sending. This field strictly shows how much |
|||
information is currently queued. |
|||
|
|||
.. c:member:: size_t uv_udp_t.send_queue_count |
|||
|
|||
Number of send requests currently in the queue awaiting to be processed. |
|||
|
|||
.. c:member:: uv_udp_t* uv_udp_send_t.handle |
|||
|
|||
UDP handle where this send request is taking place. |
|||
|
|||
.. seealso:: The :c:type:`uv_handle_t` members also apply. |
|||
|
|||
|
|||
API |
|||
--- |
|||
|
|||
.. c:function:: int uv_udp_init(uv_loop_t*, uv_udp_t* handle) |
|||
|
|||
Initialize a new UDP handle. The actual socket is created lazily. |
|||
Returns 0 on success. |
|||
|
|||
.. c:function:: int uv_udp_open(uv_udp_t* handle, uv_os_sock_t sock) |
|||
|
|||
Opens an existing file descriptor or Windows SOCKET as a UDP handle. |
|||
|
|||
Unix only: |
|||
The only requirement of the `sock` argument is that it follows the datagram |
|||
contract (works in unconnected mode, supports sendmsg()/recvmsg(), etc). |
|||
In other words, other datagram-type sockets like raw sockets or netlink |
|||
sockets can also be passed to this function. |
|||
|
|||
.. c:function:: int uv_udp_bind(uv_udp_t* handle, const struct sockaddr* addr, unsigned int flags) |
|||
|
|||
Bind the UDP handle to an IP address and port. |
|||
|
|||
:param handle: UDP handle. Should have been initialized with |
|||
:c:func:`uv_udp_init`. |
|||
|
|||
:param addr: `struct sockaddr_in` or `struct sockaddr_in6` |
|||
with the address and port to bind to. |
|||
|
|||
:param flags: Indicate how the socket will be bound, |
|||
``UV_UDP_IPV6ONLY`` and ``UV_UDP_REUSEADDR`` are supported. |
|||
|
|||
:returns: 0 on success, or an error code < 0 on failure. |
|||
|
|||
.. c:function:: int uv_udp_getsockname(const uv_udp_t* handle, struct sockaddr* name, int* namelen) |
|||
|
|||
Get the local IP and port of the UDP handle. |
|||
|
|||
:param handle: UDP handle. Should have been initialized with |
|||
:c:func:`uv_udp_init` and bound. |
|||
|
|||
:param name: Pointer to the structure to be filled with the address data. |
|||
In order to support IPv4 and IPv6 `struct sockaddr_storage` should be |
|||
used. |
|||
|
|||
:param namelen: On input it indicates the data of the `name` field. On |
|||
output it indicates how much of it was filled. |
|||
|
|||
:returns: 0 on success, or an error code < 0 on failure. |
|||
|
|||
.. c:function:: int uv_udp_set_membership(uv_udp_t* handle, const char* multicast_addr, const char* interface_addr, uv_membership membership) |
|||
|
|||
Set membership for a multicast address |
|||
|
|||
:param handle: UDP handle. Should have been initialized with |
|||
:c:func:`uv_udp_init`. |
|||
|
|||
:param multicast_addr: Multicast address to set membership for. |
|||
|
|||
:param interface_addr: Interface address. |
|||
|
|||
:param membership: Should be ``UV_JOIN_GROUP`` or ``UV_LEAVE_GROUP``. |
|||
|
|||
:returns: 0 on success, or an error code < 0 on failure. |
|||
|
|||
.. c:function:: int uv_udp_set_multicast_loop(uv_udp_t* handle, int on) |
|||
|
|||
Set IP multicast loop flag. Makes multicast packets loop back to |
|||
local sockets. |
|||
|
|||
:param handle: UDP handle. Should have been initialized with |
|||
:c:func:`uv_udp_init`. |
|||
|
|||
:param on: 1 for on, 0 for off. |
|||
|
|||
:returns: 0 on success, or an error code < 0 on failure. |
|||
|
|||
.. c:function:: int uv_udp_set_multicast_ttl(uv_udp_t* handle, int ttl) |
|||
|
|||
Set the multicast ttl. |
|||
|
|||
:param handle: UDP handle. Should have been initialized with |
|||
:c:func:`uv_udp_init`. |
|||
|
|||
:param ttl: 1 through 255. |
|||
|
|||
:returns: 0 on success, or an error code < 0 on failure. |
|||
|
|||
.. c:function:: int uv_udp_set_multicast_interface(uv_udp_t* handle, const char* interface_addr) |
|||
|
|||
Set the multicast interface to send or receive data on. |
|||
|
|||
:param handle: UDP handle. Should have been initialized with |
|||
:c:func:`uv_udp_init`. |
|||
|
|||
:param interface_addr: interface address. |
|||
|
|||
:returns: 0 on success, or an error code < 0 on failure. |
|||
|
|||
.. c:function:: int uv_udp_set_broadcast(uv_udp_t* handle, int on) |
|||
|
|||
Set broadcast on or off. |
|||
|
|||
:param handle: UDP handle. Should have been initialized with |
|||
:c:func:`uv_udp_init`. |
|||
|
|||
:param on: 1 for on, 0 for off. |
|||
|
|||
:returns: 0 on success, or an error code < 0 on failure. |
|||
|
|||
.. c:function:: int uv_udp_set_ttl(uv_udp_t* handle, int ttl) |
|||
|
|||
Set the time to live. |
|||
|
|||
:param handle: UDP handle. Should have been initialized with |
|||
:c:func:`uv_udp_init`. |
|||
|
|||
:param ttl: 1 through 255. |
|||
|
|||
:returns: 0 on success, or an error code < 0 on failure. |
|||
|
|||
.. c:function:: int uv_udp_send(uv_udp_send_t* req, uv_udp_t* handle, const uv_buf_t bufs[], unsigned int nbufs, const struct sockaddr* addr, uv_udp_send_cb send_cb) |
|||
|
|||
Send data over the UDP socket. If the socket has not previously been bound |
|||
with :c:func:`uv_udp_bind` it will be bound to 0.0.0.0 |
|||
(the "all interfaces" IPv4 address) and a random port number. |
|||
|
|||
:param req: UDP request handle. Need not be initialized. |
|||
|
|||
:param handle: UDP handle. Should have been initialized with |
|||
:c:func:`uv_udp_init`. |
|||
|
|||
:param bufs: List of buffers to send. |
|||
|
|||
:param nbufs: Number of buffers in `bufs`. |
|||
|
|||
:param addr: `struct sockaddr_in` or `struct sockaddr_in6` with the |
|||
address and port of the remote peer. |
|||
|
|||
:param send_cb: Callback to invoke when the data has been sent out. |
|||
|
|||
:returns: 0 on success, or an error code < 0 on failure. |
|||
|
|||
.. c:function:: int uv_udp_try_send(uv_udp_t* handle, const uv_buf_t bufs[], unsigned int nbufs, const struct sockaddr* addr) |
|||
|
|||
Same as :c:func:`uv_udp_send`, but won't queue a send request if it can't |
|||
be completed immediately. |
|||
|
|||
:returns: >= 0: number of bytes sent (it matches the given buffer size). |
|||
< 0: negative error code (``UV_EAGAIN`` is returned when the message |
|||
can't be sent immediately). |
|||
|
|||
.. c:function:: int uv_udp_recv_start(uv_udp_t* handle, uv_alloc_cb alloc_cb, uv_udp_recv_cb recv_cb) |
|||
|
|||
Prepare for receiving data. If the socket has not previously been bound |
|||
with :c:func:`uv_udp_bind` it is bound to 0.0.0.0 (the "all interfaces" |
|||
IPv4 address) and a random port number. |
|||
|
|||
:param handle: UDP handle. Should have been initialized with |
|||
:c:func:`uv_udp_init`. |
|||
|
|||
:param alloc_cb: Callback to invoke when temporary storage is needed. |
|||
|
|||
:param recv_cb: Callback to invoke with received data. |
|||
|
|||
:returns: 0 on success, or an error code < 0 on failure. |
|||
|
|||
.. c:function:: int uv_udp_recv_stop(uv_udp_t* handle) |
|||
|
|||
Stop listening for incoming datagrams. |
|||
|
|||
:param handle: UDP handle. Should have been initialized with |
|||
:c:func:`uv_udp_init`. |
|||
|
|||
:returns: 0 on success, or an error code < 0 on failure. |
|||
|
|||
.. seealso:: The :c:type:`uv_handle_t` API functions also apply. |
|||
File diff suppressed because it is too large
@ -1,2 +1,5 @@ |
|||
# Ignore libtoolize-generated files. |
|||
*.m4 |
|||
!as_case.m4 |
|||
!dtrace.m4 |
|||
!libuv-check-flags.m4 |
|||
@ -0,0 +1,21 @@ |
|||
# AS_CASE(WORD, [PATTERN1], [IF-MATCHED1]...[DEFAULT]) |
|||
# ---------------------------------------------------- |
|||
# Expand into |
|||
# | case WORD in |
|||
# | PATTERN1) IF-MATCHED1 ;; |
|||
# | ... |
|||
# | *) DEFAULT ;; |
|||
# | esac |
|||
m4_define([_AS_CASE], |
|||
[m4_if([$#], 0, [m4_fatal([$0: too few arguments: $#])], |
|||
[$#], 1, [ *) $1 ;;], |
|||
[$#], 2, [ $1) m4_default([$2], [:]) ;;], |
|||
[ $1) m4_default([$2], [:]) ;; |
|||
$0(m4_shiftn(2, $@))])dnl |
|||
]) |
|||
m4_defun([AS_CASE], |
|||
[m4_ifval([$2$3], |
|||
[case $1 in |
|||
_AS_CASE(m4_shift($@)) |
|||
esac])]) |
|||
|
|||
@ -0,0 +1,66 @@ |
|||
dnl Copyright (C) 2009 Sun Microsystems |
|||
dnl This file is free software; Sun Microsystems |
|||
dnl gives unlimited permission to copy and/or distribute it, |
|||
dnl with or without modifications, as long as this notice is preserved. |
|||
|
|||
dnl --------------------------------------------------------------------------- |
|||
dnl Macro: PANDORA_ENABLE_DTRACE |
|||
dnl --------------------------------------------------------------------------- |
|||
AC_DEFUN([PANDORA_ENABLE_DTRACE],[ |
|||
AC_ARG_ENABLE([dtrace], |
|||
[AS_HELP_STRING([--disable-dtrace], |
|||
[enable DTrace USDT probes. @<:@default=yes@:>@])], |
|||
[ac_cv_enable_dtrace="$enableval"], |
|||
[ac_cv_enable_dtrace="yes"]) |
|||
|
|||
AS_IF([test "$ac_cv_enable_dtrace" = "yes"],[ |
|||
AC_CHECK_PROGS([DTRACE], [dtrace]) |
|||
AS_IF([test "x$ac_cv_prog_DTRACE" = "xdtrace"],[ |
|||
|
|||
AC_CACHE_CHECK([if dtrace works],[ac_cv_dtrace_works],[ |
|||
cat >conftest.d <<_ACEOF |
|||
provider Example { |
|||
probe increment(int); |
|||
}; |
|||
_ACEOF |
|||
$DTRACE -h -o conftest.h -s conftest.d 2>/dev/zero |
|||
AS_IF([test $? -eq 0],[ac_cv_dtrace_works=yes], |
|||
[ac_cv_dtrace_works=no]) |
|||
rm -f conftest.h conftest.d |
|||
]) |
|||
AS_IF([test "x$ac_cv_dtrace_works" = "xyes"],[ |
|||
AC_DEFINE([HAVE_DTRACE], [1], [Enables DTRACE Support]) |
|||
AC_CACHE_CHECK([if dtrace should instrument object files], |
|||
[ac_cv_dtrace_needs_objects],[ |
|||
dnl DTrace on MacOSX does not use -G option |
|||
cat >conftest.d <<_ACEOF |
|||
provider Example { |
|||
probe increment(int); |
|||
}; |
|||
_ACEOF |
|||
cat > conftest.c <<_ACEOF |
|||
#include "conftest.h" |
|||
void foo() { |
|||
EXAMPLE_INCREMENT(1); |
|||
} |
|||
_ACEOF |
|||
$DTRACE -h -o conftest.h -s conftest.d 2>/dev/zero |
|||
$CC -c -o conftest.o conftest.c |
|||
$DTRACE -G -o conftest.d.o -s conftest.d conftest.o 2>/dev/zero |
|||
AS_IF([test $? -eq 0],[ac_cv_dtrace_needs_objects=yes], |
|||
[ac_cv_dtrace_needs_objects=no]) |
|||
rm -f conftest.d.o conftest.d conftest.h conftest.o conftest.c |
|||
]) |
|||
]) |
|||
AC_SUBST(DTRACEFLAGS) dnl TODO: test for -G on OSX |
|||
ac_cv_have_dtrace=yes |
|||
])]) |
|||
|
|||
AM_CONDITIONAL([HAVE_DTRACE], [test "x$ac_cv_dtrace_works" = "xyes"]) |
|||
AM_CONDITIONAL([DTRACE_NEEDS_OBJECTS], |
|||
[test "x$ac_cv_dtrace_needs_objects" = "xyes"]) |
|||
|
|||
]) |
|||
dnl --------------------------------------------------------------------------- |
|||
dnl End Macro: PANDORA_ENABLE_DTRACE |
|||
dnl --------------------------------------------------------------------------- |
|||
@ -0,0 +1,319 @@ |
|||
dnl Macros to check the presence of generic (non-typed) symbols. |
|||
dnl Copyright (c) 2006-2008 Diego Pettenà <flameeyes gmail com> |
|||
dnl Copyright (c) 2006-2008 xine project |
|||
dnl |
|||
dnl This program is free software; you can redistribute it and/or modify |
|||
dnl it under the terms of the GNU General Public License as published by |
|||
dnl the Free Software Foundation; either version 3, or (at your option) |
|||
dnl any later version. |
|||
dnl |
|||
dnl This program is distributed in the hope that it will be useful, |
|||
dnl but WITHOUT ANY WARRANTY; without even the implied warranty of |
|||
dnl MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
|||
dnl GNU General Public License for more details. |
|||
dnl |
|||
dnl You should have received a copy of the GNU General Public License |
|||
dnl along with this program; if not, write to the Free Software |
|||
dnl Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA |
|||
dnl 02110-1301, USA. |
|||
dnl |
|||
dnl As a special exception, the copyright owners of the |
|||
dnl macro gives unlimited permission to copy, distribute and modify the |
|||
dnl configure scripts that are the output of Autoconf when processing the |
|||
dnl Macro. You need not follow the terms of the GNU General Public |
|||
dnl License when using or distributing such scripts, even though portions |
|||
dnl of the text of the Macro appear in them. The GNU General Public |
|||
dnl License (GPL) does govern all other use of the material that |
|||
dnl constitutes the Autoconf Macro. |
|||
dnl |
|||
dnl This special exception to the GPL applies to versions of the |
|||
dnl Autoconf Macro released by this project. When you make and |
|||
dnl distribute a modified version of the Autoconf Macro, you may extend |
|||
dnl this special exception to the GPL to apply to your modified version as |
|||
dnl well. |
|||
|
|||
dnl Check if the flag is supported by compiler |
|||
dnl CC_CHECK_CFLAGS_SILENT([FLAG], [ACTION-IF-FOUND],[ACTION-IF-NOT-FOUND]) |
|||
|
|||
AC_DEFUN([CC_CHECK_CFLAGS_SILENT], [ |
|||
AC_CACHE_VAL(AS_TR_SH([cc_cv_cflags_$1]), |
|||
[ac_save_CFLAGS="$CFLAGS" |
|||
CFLAGS="$CFLAGS $1" |
|||
AC_COMPILE_IFELSE([AC_LANG_SOURCE([int a;])], |
|||
[eval "AS_TR_SH([cc_cv_cflags_$1])='yes'"], |
|||
[eval "AS_TR_SH([cc_cv_cflags_$1])='no'"]) |
|||
CFLAGS="$ac_save_CFLAGS" |
|||
]) |
|||
|
|||
AS_IF([eval test x$]AS_TR_SH([cc_cv_cflags_$1])[ = xyes], |
|||
[$2], [$3]) |
|||
]) |
|||
|
|||
dnl Check if the flag is supported by compiler (cacheable) |
|||
dnl CC_CHECK_CFLAGS([FLAG], [ACTION-IF-FOUND],[ACTION-IF-NOT-FOUND]) |
|||
|
|||
AC_DEFUN([CC_CHECK_CFLAGS], [ |
|||
AC_CACHE_CHECK([if $CC supports $1 flag], |
|||
AS_TR_SH([cc_cv_cflags_$1]), |
|||
CC_CHECK_CFLAGS_SILENT([$1]) dnl Don't execute actions here! |
|||
) |
|||
|
|||
AS_IF([eval test x$]AS_TR_SH([cc_cv_cflags_$1])[ = xyes], |
|||
[$2], [$3]) |
|||
]) |
|||
|
|||
dnl CC_CHECK_CFLAG_APPEND(FLAG, [action-if-found], [action-if-not-found]) |
|||
dnl Check for CFLAG and appends them to CFLAGS if supported |
|||
AC_DEFUN([CC_CHECK_CFLAG_APPEND], [ |
|||
AC_CACHE_CHECK([if $CC supports $1 flag], |
|||
AS_TR_SH([cc_cv_cflags_$1]), |
|||
CC_CHECK_CFLAGS_SILENT([$1]) dnl Don't execute actions here! |
|||
) |
|||
|
|||
AS_IF([eval test x$]AS_TR_SH([cc_cv_cflags_$1])[ = xyes], |
|||
[CFLAGS="$CFLAGS $1"; DEBUG_CFLAGS="$DEBUG_CFLAGS $1"; $2], [$3]) |
|||
]) |
|||
|
|||
dnl CC_CHECK_CFLAGS_APPEND([FLAG1 FLAG2], [action-if-found], [action-if-not]) |
|||
AC_DEFUN([CC_CHECK_CFLAGS_APPEND], [ |
|||
for flag in $1; do |
|||
CC_CHECK_CFLAG_APPEND($flag, [$2], [$3]) |
|||
done |
|||
]) |
|||
|
|||
dnl Check if the flag is supported by linker (cacheable) |
|||
dnl CC_CHECK_LDFLAGS([FLAG], [ACTION-IF-FOUND],[ACTION-IF-NOT-FOUND]) |
|||
|
|||
AC_DEFUN([CC_CHECK_LDFLAGS], [ |
|||
AC_CACHE_CHECK([if $CC supports $1 flag], |
|||
AS_TR_SH([cc_cv_ldflags_$1]), |
|||
[ac_save_LDFLAGS="$LDFLAGS" |
|||
LDFLAGS="$LDFLAGS $1" |
|||
AC_LANG_PUSH([C]) |
|||
AC_LINK_IFELSE([AC_LANG_SOURCE([int main() { return 1; }])], |
|||
[eval "AS_TR_SH([cc_cv_ldflags_$1])='yes'"], |
|||
[eval "AS_TR_SH([cc_cv_ldflags_$1])="]) |
|||
AC_LANG_POP([C]) |
|||
LDFLAGS="$ac_save_LDFLAGS" |
|||
]) |
|||
|
|||
AS_IF([eval test x$]AS_TR_SH([cc_cv_ldflags_$1])[ = xyes], |
|||
[$2], [$3]) |
|||
]) |
|||
|
|||
dnl define the LDFLAGS_NOUNDEFINED variable with the correct value for |
|||
dnl the current linker to avoid undefined references in a shared object. |
|||
AC_DEFUN([CC_NOUNDEFINED], [ |
|||
dnl We check $host for which systems to enable this for. |
|||
AC_REQUIRE([AC_CANONICAL_HOST]) |
|||
|
|||
case $host in |
|||
dnl FreeBSD (et al.) does not complete linking for shared objects when pthreads |
|||
dnl are requested, as different implementations are present; to avoid problems |
|||
dnl use -Wl,-z,defs only for those platform not behaving this way. |
|||
*-freebsd* | *-openbsd*) ;; |
|||
*) |
|||
dnl First of all check for the --no-undefined variant of GNU ld. This allows |
|||
dnl for a much more readable commandline, so that people can understand what |
|||
dnl it does without going to look for what the heck -z defs does. |
|||
for possible_flags in "-Wl,--no-undefined" "-Wl,-z,defs"; do |
|||
CC_CHECK_LDFLAGS([$possible_flags], [LDFLAGS_NOUNDEFINED="$possible_flags"]) |
|||
break |
|||
done |
|||
;; |
|||
esac |
|||
|
|||
AC_SUBST([LDFLAGS_NOUNDEFINED]) |
|||
]) |
|||
|
|||
dnl Check for a -Werror flag or equivalent. -Werror is the GCC |
|||
dnl and ICC flag that tells the compiler to treat all the warnings |
|||
dnl as fatal. We usually need this option to make sure that some |
|||
dnl constructs (like attributes) are not simply ignored. |
|||
dnl |
|||
dnl Other compilers don't support -Werror per se, but they support |
|||
dnl an equivalent flag: |
|||
dnl - Sun Studio compiler supports -errwarn=%all |
|||
AC_DEFUN([CC_CHECK_WERROR], [ |
|||
AC_CACHE_CHECK( |
|||
[for $CC way to treat warnings as errors], |
|||
[cc_cv_werror], |
|||
[CC_CHECK_CFLAGS_SILENT([-Werror], [cc_cv_werror=-Werror], |
|||
[CC_CHECK_CFLAGS_SILENT([-errwarn=%all], [cc_cv_werror=-errwarn=%all])]) |
|||
]) |
|||
]) |
|||
|
|||
AC_DEFUN([CC_CHECK_ATTRIBUTE], [ |
|||
AC_REQUIRE([CC_CHECK_WERROR]) |
|||
AC_CACHE_CHECK([if $CC supports __attribute__(( ifelse([$2], , [$1], [$2]) ))], |
|||
AS_TR_SH([cc_cv_attribute_$1]), |
|||
[ac_save_CFLAGS="$CFLAGS" |
|||
CFLAGS="$CFLAGS $cc_cv_werror" |
|||
AC_LANG_PUSH([C]) |
|||
AC_COMPILE_IFELSE([AC_LANG_SOURCE([$3])], |
|||
[eval "AS_TR_SH([cc_cv_attribute_$1])='yes'"], |
|||
[eval "AS_TR_SH([cc_cv_attribute_$1])='no'"]) |
|||
AC_LANG_POP([C]) |
|||
CFLAGS="$ac_save_CFLAGS" |
|||
]) |
|||
|
|||
AS_IF([eval test x$]AS_TR_SH([cc_cv_attribute_$1])[ = xyes], |
|||
[AC_DEFINE( |
|||
AS_TR_CPP([SUPPORT_ATTRIBUTE_$1]), 1, |
|||
[Define this if the compiler supports __attribute__(( ifelse([$2], , [$1], [$2]) ))] |
|||
) |
|||
$4], |
|||
[$5]) |
|||
]) |
|||
|
|||
AC_DEFUN([CC_ATTRIBUTE_CONSTRUCTOR], [ |
|||
CC_CHECK_ATTRIBUTE( |
|||
[constructor],, |
|||
[void __attribute__((constructor)) ctor() { int a; }], |
|||
[$1], [$2]) |
|||
]) |
|||
|
|||
AC_DEFUN([CC_ATTRIBUTE_FORMAT], [ |
|||
CC_CHECK_ATTRIBUTE( |
|||
[format], [format(printf, n, n)], |
|||
[void __attribute__((format(printf, 1, 2))) printflike(const char *fmt, ...) { fmt = (void *)0; }], |
|||
[$1], [$2]) |
|||
]) |
|||
|
|||
AC_DEFUN([CC_ATTRIBUTE_FORMAT_ARG], [ |
|||
CC_CHECK_ATTRIBUTE( |
|||
[format_arg], [format_arg(printf)], |
|||
[char *__attribute__((format_arg(1))) gettextlike(const char *fmt) { fmt = (void *)0; }], |
|||
[$1], [$2]) |
|||
]) |
|||
|
|||
AC_DEFUN([CC_ATTRIBUTE_VISIBILITY], [ |
|||
CC_CHECK_ATTRIBUTE( |
|||
[visibility_$1], [visibility("$1")], |
|||
[void __attribute__((visibility("$1"))) $1_function() { }], |
|||
[$2], [$3]) |
|||
]) |
|||
|
|||
AC_DEFUN([CC_ATTRIBUTE_NONNULL], [ |
|||
CC_CHECK_ATTRIBUTE( |
|||
[nonnull], [nonnull()], |
|||
[void __attribute__((nonnull())) some_function(void *foo, void *bar) { foo = (void*)0; bar = (void*)0; }], |
|||
[$1], [$2]) |
|||
]) |
|||
|
|||
AC_DEFUN([CC_ATTRIBUTE_UNUSED], [ |
|||
CC_CHECK_ATTRIBUTE( |
|||
[unused], , |
|||
[void some_function(void *foo, __attribute__((unused)) void *bar);], |
|||
[$1], [$2]) |
|||
]) |
|||
|
|||
AC_DEFUN([CC_ATTRIBUTE_SENTINEL], [ |
|||
CC_CHECK_ATTRIBUTE( |
|||
[sentinel], , |
|||
[void some_function(void *foo, ...) __attribute__((sentinel));], |
|||
[$1], [$2]) |
|||
]) |
|||
|
|||
AC_DEFUN([CC_ATTRIBUTE_DEPRECATED], [ |
|||
CC_CHECK_ATTRIBUTE( |
|||
[deprecated], , |
|||
[void some_function(void *foo, ...) __attribute__((deprecated));], |
|||
[$1], [$2]) |
|||
]) |
|||
|
|||
AC_DEFUN([CC_ATTRIBUTE_ALIAS], [ |
|||
CC_CHECK_ATTRIBUTE( |
|||
[alias], [weak, alias], |
|||
[void other_function(void *foo) { } |
|||
void some_function(void *foo) __attribute__((weak, alias("other_function")));], |
|||
[$1], [$2]) |
|||
]) |
|||
|
|||
AC_DEFUN([CC_ATTRIBUTE_MALLOC], [ |
|||
CC_CHECK_ATTRIBUTE( |
|||
[malloc], , |
|||
[void * __attribute__((malloc)) my_alloc(int n);], |
|||
[$1], [$2]) |
|||
]) |
|||
|
|||
AC_DEFUN([CC_ATTRIBUTE_PACKED], [ |
|||
CC_CHECK_ATTRIBUTE( |
|||
[packed], , |
|||
[struct astructure { char a; int b; long c; void *d; } __attribute__((packed));], |
|||
[$1], [$2]) |
|||
]) |
|||
|
|||
AC_DEFUN([CC_ATTRIBUTE_CONST], [ |
|||
CC_CHECK_ATTRIBUTE( |
|||
[const], , |
|||
[int __attribute__((const)) twopow(int n) { return 1 << n; } ], |
|||
[$1], [$2]) |
|||
]) |
|||
|
|||
AC_DEFUN([CC_FLAG_VISIBILITY], [ |
|||
AC_REQUIRE([CC_CHECK_WERROR]) |
|||
AC_CACHE_CHECK([if $CC supports -fvisibility=hidden], |
|||
[cc_cv_flag_visibility], |
|||
[cc_flag_visibility_save_CFLAGS="$CFLAGS" |
|||
CFLAGS="$CFLAGS $cc_cv_werror" |
|||
CC_CHECK_CFLAGS_SILENT([-fvisibility=hidden], |
|||
cc_cv_flag_visibility='yes', |
|||
cc_cv_flag_visibility='no') |
|||
CFLAGS="$cc_flag_visibility_save_CFLAGS"]) |
|||
|
|||
AS_IF([test "x$cc_cv_flag_visibility" = "xyes"], |
|||
[AC_DEFINE([SUPPORT_FLAG_VISIBILITY], 1, |
|||
[Define this if the compiler supports the -fvisibility flag]) |
|||
$1], |
|||
[$2]) |
|||
]) |
|||
|
|||
AC_DEFUN([CC_FUNC_EXPECT], [ |
|||
AC_REQUIRE([CC_CHECK_WERROR]) |
|||
AC_CACHE_CHECK([if compiler has __builtin_expect function], |
|||
[cc_cv_func_expect], |
|||
[ac_save_CFLAGS="$CFLAGS" |
|||
CFLAGS="$CFLAGS $cc_cv_werror" |
|||
AC_LANG_PUSH([C]) |
|||
AC_COMPILE_IFELSE([AC_LANG_SOURCE( |
|||
[int some_function() { |
|||
int a = 3; |
|||
return (int)__builtin_expect(a, 3); |
|||
}])], |
|||
[cc_cv_func_expect=yes], |
|||
[cc_cv_func_expect=no]) |
|||
AC_LANG_POP([C]) |
|||
CFLAGS="$ac_save_CFLAGS" |
|||
]) |
|||
|
|||
AS_IF([test "x$cc_cv_func_expect" = "xyes"], |
|||
[AC_DEFINE([SUPPORT__BUILTIN_EXPECT], 1, |
|||
[Define this if the compiler supports __builtin_expect() function]) |
|||
$1], |
|||
[$2]) |
|||
]) |
|||
|
|||
AC_DEFUN([CC_ATTRIBUTE_ALIGNED], [ |
|||
AC_REQUIRE([CC_CHECK_WERROR]) |
|||
AC_CACHE_CHECK([highest __attribute__ ((aligned ())) supported], |
|||
[cc_cv_attribute_aligned], |
|||
[ac_save_CFLAGS="$CFLAGS" |
|||
CFLAGS="$CFLAGS $cc_cv_werror" |
|||
AC_LANG_PUSH([C]) |
|||
for cc_attribute_align_try in 64 32 16 8 4 2; do |
|||
AC_COMPILE_IFELSE([AC_LANG_SOURCE([ |
|||
int main() { |
|||
static char c __attribute__ ((aligned($cc_attribute_align_try))) = 0; |
|||
return c; |
|||
}])], [cc_cv_attribute_aligned=$cc_attribute_align_try; break]) |
|||
done |
|||
AC_LANG_POP([C]) |
|||
CFLAGS="$ac_save_CFLAGS" |
|||
]) |
|||
|
|||
if test "x$cc_cv_attribute_aligned" != "x"; then |
|||
AC_DEFINE_UNQUOTED([ATTRIBUTE_ALIGNED_MAX], [$cc_cv_attribute_aligned], |
|||
[Define the highest alignment supported]) |
|||
fi |
|||
]) |
|||
@ -0,0 +1,59 @@ |
|||
/* Copyright Joyent, Inc. and other Node contributors. All rights reserved.
|
|||
* |
|||
* Permission is hereby granted, free of charge, to any person obtaining a copy |
|||
* of this software and associated documentation files (the "Software"), to |
|||
* deal in the Software without restriction, including without limitation the |
|||
* rights to use, copy, modify, merge, publish, distribute, sublicense, and/or |
|||
* sell copies of the Software, and to permit persons to whom the Software is |
|||
* furnished to do so, subject to the following conditions: |
|||
* |
|||
* The above copyright notice and this permission notice shall be included in |
|||
* all copies or substantial portions of the Software. |
|||
* |
|||
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
|||
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
|||
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE |
|||
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER |
|||
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING |
|||
* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS |
|||
* IN THE SOFTWARE. |
|||
*/ |
|||
|
|||
#include "uv.h" |
|||
#include "task.h" |
|||
|
|||
|
|||
static int timer_cb_called; |
|||
|
|||
|
|||
static void timer_cb(uv_timer_t* timer) { |
|||
timer_cb_called++; |
|||
uv_close((uv_handle_t*) timer, NULL); |
|||
} |
|||
|
|||
|
|||
TEST_IMPL(default_loop_close) { |
|||
uv_loop_t* loop; |
|||
uv_timer_t timer_handle; |
|||
|
|||
loop = uv_default_loop(); |
|||
ASSERT(loop != NULL); |
|||
|
|||
ASSERT(0 == uv_timer_init(loop, &timer_handle)); |
|||
ASSERT(0 == uv_timer_start(&timer_handle, timer_cb, 1, 0)); |
|||
ASSERT(0 == uv_run(loop, UV_RUN_DEFAULT)); |
|||
ASSERT(1 == timer_cb_called); |
|||
ASSERT(0 == uv_loop_close(loop)); |
|||
|
|||
loop = uv_default_loop(); |
|||
ASSERT(loop != NULL); |
|||
|
|||
ASSERT(0 == uv_timer_init(loop, &timer_handle)); |
|||
ASSERT(0 == uv_timer_start(&timer_handle, timer_cb, 1, 0)); |
|||
ASSERT(0 == uv_run(loop, UV_RUN_DEFAULT)); |
|||
ASSERT(2 == timer_cb_called); |
|||
ASSERT(0 == uv_loop_close(loop)); |
|||
|
|||
MAKE_VALGRIND_HAPPY(); |
|||
return 0; |
|||
} |
|||
@ -0,0 +1,120 @@ |
|||
/* Copyright Joyent, Inc. and other Node contributors. All rights reserved.
|
|||
* |
|||
* Permission is hereby granted, free of charge, to any person obtaining a copy |
|||
* of this software and associated documentation files (the "Software"), to |
|||
* deal in the Software without restriction, including without limitation the |
|||
* rights to use, copy, modify, merge, publish, distribute, sublicense, and/or |
|||
* sell copies of the Software, and to permit persons to whom the Software is |
|||
* furnished to do so, subject to the following conditions: |
|||
* |
|||
* The above copyright notice and this permission notice shall be included in |
|||
* all copies or substantial portions of the Software. |
|||
* |
|||
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
|||
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
|||
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE |
|||
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER |
|||
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING |
|||
* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS |
|||
* IN THE SOFTWARE. |
|||
*/ |
|||
|
|||
#include "uv.h" |
|||
#include "task.h" |
|||
|
|||
|
|||
static int get_tty_fd(void) { |
|||
/* Make sure we have an FD that refers to a tty */ |
|||
#ifdef _WIN32 |
|||
HANDLE handle; |
|||
handle = CreateFileA("conout$", |
|||
GENERIC_READ | GENERIC_WRITE, |
|||
FILE_SHARE_READ | FILE_SHARE_WRITE, |
|||
NULL, |
|||
OPEN_EXISTING, |
|||
FILE_ATTRIBUTE_NORMAL, |
|||
NULL); |
|||
if (handle == INVALID_HANDLE_VALUE) |
|||
return -1; |
|||
return _open_osfhandle((intptr_t) handle, 0); |
|||
#else /* unix */ |
|||
return open("/dev/tty", O_RDONLY, 0); |
|||
#endif |
|||
} |
|||
|
|||
|
|||
TEST_IMPL(handle_fileno) { |
|||
int r; |
|||
int tty_fd; |
|||
struct sockaddr_in addr; |
|||
uv_os_fd_t fd; |
|||
uv_tcp_t tcp; |
|||
uv_udp_t udp; |
|||
uv_pipe_t pipe; |
|||
uv_tty_t tty; |
|||
uv_idle_t idle; |
|||
uv_loop_t* loop; |
|||
|
|||
loop = uv_default_loop(); |
|||
ASSERT(0 == uv_ip4_addr("127.0.0.1", TEST_PORT, &addr)); |
|||
|
|||
r = uv_idle_init(loop, &idle); |
|||
ASSERT(r == 0); |
|||
r = uv_fileno((uv_handle_t*) &idle, &fd); |
|||
ASSERT(r == UV_EINVAL); |
|||
uv_close((uv_handle_t*) &idle, NULL); |
|||
|
|||
r = uv_tcp_init(loop, &tcp); |
|||
ASSERT(r == 0); |
|||
r = uv_fileno((uv_handle_t*) &tcp, &fd); |
|||
ASSERT(r == UV_EBADF); |
|||
r = uv_tcp_bind(&tcp, (const struct sockaddr*) &addr, 0); |
|||
ASSERT(r == 0); |
|||
r = uv_fileno((uv_handle_t*) &tcp, &fd); |
|||
ASSERT(r == 0); |
|||
uv_close((uv_handle_t*) &tcp, NULL); |
|||
r = uv_fileno((uv_handle_t*) &tcp, &fd); |
|||
ASSERT(r == UV_EBADF); |
|||
|
|||
r = uv_udp_init(loop, &udp); |
|||
ASSERT(r == 0); |
|||
r = uv_fileno((uv_handle_t*) &udp, &fd); |
|||
ASSERT(r == UV_EBADF); |
|||
r = uv_udp_bind(&udp, (const struct sockaddr*) &addr, 0); |
|||
ASSERT(r == 0); |
|||
r = uv_fileno((uv_handle_t*) &udp, &fd); |
|||
ASSERT(r == 0); |
|||
uv_close((uv_handle_t*) &udp, NULL); |
|||
r = uv_fileno((uv_handle_t*) &udp, &fd); |
|||
ASSERT(r == UV_EBADF); |
|||
|
|||
r = uv_pipe_init(loop, &pipe, 0); |
|||
ASSERT(r == 0); |
|||
r = uv_fileno((uv_handle_t*) &pipe, &fd); |
|||
ASSERT(r == UV_EBADF); |
|||
r = uv_pipe_bind(&pipe, TEST_PIPENAME); |
|||
ASSERT(r == 0); |
|||
r = uv_fileno((uv_handle_t*) &pipe, &fd); |
|||
ASSERT(r == 0); |
|||
uv_close((uv_handle_t*) &pipe, NULL); |
|||
r = uv_fileno((uv_handle_t*) &pipe, &fd); |
|||
ASSERT(r == UV_EBADF); |
|||
|
|||
tty_fd = get_tty_fd(); |
|||
if (tty_fd < 0) { |
|||
LOGF("Cannot open a TTY fd"); |
|||
} else { |
|||
r = uv_tty_init(loop, &tty, tty_fd, 0); |
|||
ASSERT(r == 0); |
|||
r = uv_fileno((uv_handle_t*) &tty, &fd); |
|||
ASSERT(r == 0); |
|||
uv_close((uv_handle_t*) &tty, NULL); |
|||
r = uv_fileno((uv_handle_t*) &tty, &fd); |
|||
ASSERT(r == UV_EBADF); |
|||
} |
|||
|
|||
uv_run(loop, UV_RUN_DEFAULT); |
|||
|
|||
MAKE_VALGRIND_HAPPY(); |
|||
return 0; |
|||
} |
|||
@ -0,0 +1,103 @@ |
|||
/* Copyright Joyent, Inc. and other Node contributors. All rights reserved.
|
|||
* |
|||
* Permission is hereby granted, free of charge, to any person obtaining a copy |
|||
* of this software and associated documentation files (the "Software"), to |
|||
* deal in the Software without restriction, including without limitation the |
|||
* rights to use, copy, modify, merge, publish, distribute, sublicense, and/or |
|||
* sell copies of the Software, and to permit persons to whom the Software is |
|||
* furnished to do so, subject to the following conditions: |
|||
* |
|||
* The above copyright notice and this permission notice shall be included in |
|||
* all copies or substantial portions of the Software. |
|||
* |
|||
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
|||
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
|||
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE |
|||
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER |
|||
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING |
|||
* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS |
|||
* IN THE SOFTWARE. |
|||
*/ |
|||
|
|||
#ifndef _WIN32 |
|||
|
|||
#include <stdlib.h> |
|||
#include <unistd.h> |
|||
#include <sys/wait.h> |
|||
#include <sys/types.h> |
|||
|
|||
#include "uv.h" |
|||
#include "task.h" |
|||
|
|||
void alloc_buffer(uv_handle_t *handle, size_t suggested_size, uv_buf_t* buf) |
|||
{ |
|||
static char buffer[1024]; |
|||
|
|||
buf->base = buffer; |
|||
buf->len = sizeof(buffer); |
|||
} |
|||
|
|||
void read_stdin(uv_stream_t *stream, ssize_t nread, const uv_buf_t* buf) |
|||
{ |
|||
if (nread < 0) { |
|||
uv_close((uv_handle_t*)stream, NULL); |
|||
return; |
|||
} |
|||
} |
|||
|
|||
/*
|
|||
* This test is a reproduction of joyent/libuv#1419 . |
|||
*/ |
|||
TEST_IMPL(pipe_close_stdout_read_stdin) { |
|||
int r = -1; |
|||
int pid; |
|||
int fd[2]; |
|||
int status; |
|||
|
|||
pipe(fd); |
|||
|
|||
if ((pid = fork()) == 0) { |
|||
/*
|
|||
* Make the read side of the pipe our stdin. |
|||
* The write side will be closed by the parent process. |
|||
*/ |
|||
close(fd[1]); |
|||
close(0); |
|||
dup(fd[0]); |
|||
|
|||
/* Create a stream that reads from the pipe. */ |
|||
uv_pipe_t stdin_pipe; |
|||
|
|||
r = uv_pipe_init(uv_default_loop(), (uv_pipe_t *)&stdin_pipe, 0); |
|||
ASSERT(r == 0); |
|||
|
|||
r = uv_pipe_open((uv_pipe_t *)&stdin_pipe, 0); |
|||
ASSERT(r == 0); |
|||
|
|||
r = uv_read_start((uv_stream_t *)&stdin_pipe, alloc_buffer, read_stdin); |
|||
ASSERT(r == 0); |
|||
|
|||
/*
|
|||
* Because the other end of the pipe was closed, there should |
|||
* be no event left to process after one run of the event loop. |
|||
* Otherwise, it means that events were not processed correctly. |
|||
*/ |
|||
ASSERT(uv_run(uv_default_loop(), UV_RUN_NOWAIT) == 0); |
|||
} else { |
|||
/*
|
|||
* Close both ends of the pipe so that the child |
|||
* get a POLLHUP event when it tries to read from |
|||
* the other end. |
|||
*/ |
|||
close(fd[1]); |
|||
close(fd[0]); |
|||
|
|||
waitpid(pid, &status, 0); |
|||
ASSERT(WIFEXITED(status) && WEXITSTATUS(status) == 0); |
|||
} |
|||
|
|||
MAKE_VALGRIND_HAPPY(); |
|||
return 0; |
|||
} |
|||
|
|||
#endif /* ifndef _WIN32 */ |
|||
@ -0,0 +1,77 @@ |
|||
/* Copyright Joyent, Inc. and other Node contributors. All rights reserved.
|
|||
* |
|||
* Permission is hereby granted, free of charge, to any person obtaining a copy |
|||
* of this software and associated documentation files (the "Software"), to |
|||
* deal in the Software without restriction, including without limitation the |
|||
* rights to use, copy, modify, merge, publish, distribute, sublicense, and/or |
|||
* sell copies of the Software, and to permit persons to whom the Software is |
|||
* furnished to do so, subject to the following conditions: |
|||
* |
|||
* The above copyright notice and this permission notice shall be included in |
|||
* all copies or substantial portions of the Software. |
|||
* |
|||
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
|||
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
|||
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE |
|||
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER |
|||
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING |
|||
* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS |
|||
* IN THE SOFTWARE. |
|||
*/ |
|||
|
|||
#include "uv.h" |
|||
#include "task.h" |
|||
|
|||
#include <stdio.h> |
|||
#include <stdlib.h> |
|||
#include <string.h> |
|||
|
|||
static uv_udp_t udp; |
|||
static uv_tcp_t tcp; |
|||
static int close_cb_called; |
|||
|
|||
|
|||
static void close_cb(uv_handle_t* handle) { |
|||
close_cb_called++; |
|||
} |
|||
|
|||
|
|||
static void check_buffer_size(uv_handle_t* handle) { |
|||
int value; |
|||
|
|||
value = 0; |
|||
ASSERT(0 == uv_recv_buffer_size(handle, &value)); |
|||
ASSERT(value > 0); |
|||
|
|||
value = 10000; |
|||
ASSERT(0 == uv_recv_buffer_size(handle, &value)); |
|||
|
|||
value = 0; |
|||
ASSERT(0 == uv_recv_buffer_size(handle, &value)); |
|||
/* linux sets double the value */ |
|||
ASSERT(value == 10000 || value == 20000); |
|||
} |
|||
|
|||
|
|||
TEST_IMPL(socket_buffer_size) { |
|||
struct sockaddr_in addr; |
|||
|
|||
ASSERT(0 == uv_ip4_addr("127.0.0.1", TEST_PORT, &addr)); |
|||
|
|||
ASSERT(0 == uv_tcp_init(uv_default_loop(), &tcp)); |
|||
ASSERT(0 == uv_tcp_bind(&tcp, (struct sockaddr*) &addr, 0)); |
|||
check_buffer_size((uv_handle_t*) &tcp); |
|||
uv_close((uv_handle_t*) &tcp, close_cb); |
|||
|
|||
ASSERT(0 == uv_udp_init(uv_default_loop(), &udp)); |
|||
ASSERT(0 == uv_udp_bind(&udp, (struct sockaddr*) &addr, 0)); |
|||
check_buffer_size((uv_handle_t*) &udp); |
|||
uv_close((uv_handle_t*) &udp, close_cb); |
|||
|
|||
ASSERT(0 == uv_run(uv_default_loop(), UV_RUN_DEFAULT)); |
|||
|
|||
ASSERT(close_cb_called == 2); |
|||
|
|||
MAKE_VALGRIND_HAPPY(); |
|||
return 0; |
|||
} |
|||
Some files were not shown because too many files changed in this diff
Loading…
Reference in new issue