Skip to content

Instantly share code, notes, and snippets.



Last active Mar 31, 2019
What would you like to do?
#!/usr/bin/env python3
import glob
from tiles import t, emptyln
from schema import Schema, Optional, Or
# TODO: get rid of this
def trimrect(s):
return ""
# Use dill_ prefix depending on whether the result goes into docs or code.
def dillify(t, dill):
if not dill:
return t
parts = t.split()
if len(parts) and parts[0] == "struct":
return "struct dill_" + " ".join(parts[1:])
elif len(parts) >= 2 and parts[0] == "const" and parts[1] == "struct":
return "const struct dill_" + " ".join(parts[2:])
return "dill_" + t
def signature(fx, prefix="", code=False):
args = "void);"
if len(fx["args"]) > 0:
if code:
fmt = '@{dillify(arg["type"], arg["dill"])} @{arg["name"]}@{arg["suffix"]}'
fmt = '@{arg["type"]} @{arg["name"]}@{arg["suffix"]}'
args = (t/",").vjoin([t/fmt for arg in fx["args"]], last=t/");")
return t/"""
@{prefix} @{fx["result"]["type"] if fx["result"] else "void"} @{"dill_" if code else ""}@{fx["name"]}(
# Read all topic files.
files = glob.glob("*")
for file in files:
with open(file, 'r') as f:
c =
# Read all topic files.
fxs = []
files = glob.glob("*")
for file in files:
with open(file, 'r') as f:
c =
# Check for duplicate functions.
names = {}
for fx in fxs:
if fx["name"] in names:
raise ValueError("Duplicate function name %s" % fx["name"])
schema = Schema([{
# name of the function
"name": str,
# the name of the section in the docs the function should appear in
# if omitted, it will be retrieved from the protocol
Optional("topic", default=None): str,
# short description of the function
"info": str,
# which headerfile is the funcion declared in
Optional("header", default='libdill.h'): str,
# arguments of the function
"args": [{
# name of the argument
"name": str,
# type of the argument (omit for expressions)
Optional("type", default=""): str,
# part of the type to go after the name (e.g. "[]")
Optional("suffix", default=""): str,
# set to true for dill-specific types
Optional("dill", default=False): bool,
# description of the argument
"info": str,
# omit this field for void functions
Optional("result", default=None): {
# return type of the function
"type": str,
Optional("success", default=None): str,
Optional("error", default=None): str,
Optional("info", default=None): str,
# the part of the description of the function to go before the list
# of arguments
"prologue": str,
# the part of the description of the function to go after the list
# of arguments
Optional("epilogue", default=None): str,
# should be present only if the function is related to a network protocol
Optional("protocol", default=None): {
# the section in the docs the protocol belongs to
"topic": str,
# type of the protocol
"type": Or("bytestream", "message", "application"),
# description of the protocol
"info": str,
# example of usage of the protocol, a piece of C code
"example": str,
# if true, the docs will contain a warning about using this protocol
Optional("experimental", default=False): bool,
# a piece of code to be added to synopsis, between the include
# and the function declaration
Optional("add_to_synopsis", default=None): str,
Optional("add_to_errors", default=None): str,
# set to true is the function allocates at least one handle
Optional("allocates_handle", default=False): bool,
# set to true if at least one of the arguments is a handle
Optional("has_handle_argument", default=False): bool,
# if true, adds deadline to the list of arguments
Optional("has_deadline", default=False): bool,
Optional("uses_connection", default=False): bool,
# if true, adds I/O list to the list of arguments
Optional("has_iol", default=False): bool,
# if set, _mem variant of the function will be generated;
# value if the name of the storage struct, e.g. "tcp_storage".
Optional("mem"): str,
# a list of possible errors, the descriptions will be pulled from
# standard_errors object
Optional("errors", default=[]): [str],
# custom errors take precedence over standard errors
# value maps error names to error descriptions
Optional("custom_errors", default={}): {str: str},
# example of the usage of the function, a piece of C code;
# if present, it overrides the protocol example
Optional("example", default=None): str,
# if true, the docs will contain a warning about using this function
Optional("experimental", default=False): bool,
# if true, generates function signature into header file
Optional("signature", default=True): bool,
# if true, generates boiles plate code for the function
Optional("boilerplate", default=True): bool,
# Check whether the data comply to the schema. Also fills in defaults.
fxs = schema.validate(fxs)
# Collect the topics.
topics = {}
for fx in fxs:
if fx["topic"]:
topic = fx["topic"]
elif fx["protocol"]:
topic = fx["protocol"]["topic"]
fx["topic"] = topic
raise ValueError("Missing topic in %s" % fx["name"])
if topic not in topics:
topics[topic] = []
for topic, flist in topics.items():
flist.sort(key=lambda f : f["name"])
# Enhance the data.
for fx in fxs:
if fx["has_iol"]:
"name": "first",
"type": "struct iolist*",
"dill": True,
"info": "Pointer to the first item of a linked list of I/O buffers.",
"suffix": "",
"name": "last",
"type": "struct iolist*",
"dill": True,
"info": "Pointer to the last item of a linked list of I/O buffers.",
"suffix": "",
if fx["has_deadline"]:
"name": "deadline",
"type": "int64_t",
"dill": False,
"info": "A point in time when the operation should time out, in " +
"milliseconds. Use the **now** function to get your current" +
" point in time. 0 means immediate timeout, i.e., perform " +
"the operation if possible or return without blocking if " +
"not. -1 means no deadline, i.e., the call will block " +
"forever if the operation cannot be performed.",
"suffix": "",
if fx["has_handle_argument"]:
if fx["has_deadline"]:
if fx["name"] != "msleep":
if fx["allocates_handle"]:
if fx["uses_connection"]:
# TODO: if(fx.mem && !mem) errs.push("ENOMEM")
# Generate table of contents
toc = ""
topic_order = [
"File descriptors",
"Bytestream sockets",
"Message sockets",
"IP addresses",
"Happy Eyeballs protocol",
"HTTP protocol",
"IPC protocol",
"PREFIX protocol",
"SUFFIX protocol",
"TCP protocol",
"TERM protocol",
"TLS protocol",
"UDP protocol",
"WebSocket protocol"]
for topic in topics:
if topic not in topic_order:
raise ValueError("Topic %s missing in the topic order" % topic)
toc = t/""
for topic in topic_order:
flist = [f["name"] for f in topics[topic]]
items = (t/"").vjoin([t/"[@{f}(3)](@{f}.html)" for f in flist])
toc |= t%'#### @{topic}' | emptyln | items | emptyln
with open("", 'w') as f:
# Generate manpages for individual functions.
for fx in fxs:
# SYNOPSIS section
synopsis = t/'#include<@{fx["header"]}>'
if fx["add_to_synopsis"]:
synopsis |= emptyln | t/'@{fx["add_to_synopsis"]}'
synopsis |= emptyln | t/'@{signature(fx)}'
description = t/'@{fx["prologue"]}'
if fx["protocol"]:
description = t/'@{fx["protocol"]["info"]}' | emptyln | description
if fx["experimental"] or (fx["protocol"] and fx["protocol"]["experimental"]):
description = t/'**WARNING: This is experimental functionality and the API may change in the future.**' | emptyln | description
if fx["has_iol"]:
description |= emptyln | t/"""
This function accepts a linked list of I/O buffers instead of a
single buffer. Argument **first** points to the first item in the
list, **last** points to the last buffer in the list. The list
represents a single, fragmented message, not a list of multiple
messages. Structure **iolist** has the following members:
void *iol_base; /* Pointer to the buffer. */
size_t iol_len; /* Size of the buffer. */
struct iolist *iol_next; /* Next buffer in the list. */
int iol_rsvd; /* Reserved. Must be set to zero. */
When receiving, **iol_base** equal to NULL means that **iol_len**
bytes should be skipped.
The function returns **EINVAL** error in the case the list is
* If **last->iol_next** is not **NULL**.
* If **first** and **last** don't belong to the same list.
* If there's a loop in the list.
* If **iol_rsvd** of any item is non-zero.
The list (but not the buffers themselves) can be temporarily
modified while the function is in progress. However, once the
function returns the list is guaranteed to be the same as before
the call.
if fx["args"]:
description |= emptyln | (t/'').vjoin([t/'**@{arg["name"]}**: @{arg["info"]}' for arg in fx["args"]])
if fx["epilogue"]:
description |= emptyln | t/'@{fx["epilogue"]}'
if fx["protocol"] or fx["topic"] == "IP addresses":
description |= emptyln | t/'This function is not available if libdill is compiled with **--disable-sockets** option.'
if fx["protocol"] and fx["protocol"]["topic"] == "TLS protocol":
description |= emptyln | t/'This function is not available if libdill is compiled without **--enable-tls** option.'
# RETURN VALUE section
if fx["result"]:
if fx["result"]["success"] and fx["result"]["error"]:
retval = t/"""
In case of success the function returns @{fx["result"]["success"]}.
'In case of error it returns @{fx["result"]["error"]} and sets **errno** to one of the values below.
if fx["result"]["info"]:
retval = t/'@{fx["result"]["info"]}'
retval = t/"None."
# ERRORS section
standard_errors = {
"EBADF": "Invalid handle.",
"EBUSY": "The handle is currently being used by a different coroutine.",
"ETIMEDOUT": "Deadline was reached.",
"ENOMEM": "Not enough memory.",
"EMFILE": "The maximum number of file descriptors in the process are already open.",
"ENFILE": "The maximum number of file descriptors in the system are already open.",
"EINVAL": "Invalid argument.",
"EMSGSIZE": "The data won't fit into the supplied buffer.",
"ECONNRESET": "Broken connection.",
"ECANCELED": "Current coroutine was canceled.",
"ENOTSUP": "The handle does not support this operation.",
errs = {}
for e in fx["errors"]:
errs[e] = standard_errors[e]
errors = t/"None."
if len(errs) > 0:
errors = (t/'').vjoin([t/'* **@{e}**: @{desc}' for e, desc in sorted(errs.items())])
if fx["add_to_errors"]:
errors |= emptyln | t/'@{fx["add_to_errors"]}'
# Generate the manpage.
page = t/"""
@{fx["name"]} - @{fx["info"]}
# Add EXAMPLE section, if available.
example = ""
if fx["protocol"] and fx["protocol"]["example"]:
example = t/'@{fx["protocol"]["example"]}'
if fx["example"]:
example = t/'@{fx["example"]}'
if example:
page |= emptyln | t/"""
# SEE ALSO section.
# It'll contain all funrction from the same topic plus the functions
# added manually.
sa = [f["name"] for f in topics[fx["topic"]] if f["name"] != fx["name"]]
if fx["has_deadline"]:
if fx["allocates_handle"]:
if fx["protocol"] and fx["protocol"]["type"] == "bytestream":
if fx["protocol"] and fx["protocol"]["type"] == "message":
# Remove duplicates and list them in alphabetical order.
sa = list(set(sa))
#seealso = t/""
#for f in sa:
# seealso += t/"**@{f}**(3) "
seealso = (t%' ').join([t/'**@{f}**(3)' for f in sa])
page |= emptyln | t/"""
with open(fx["name"] + ".md", 'w') as f:
# Generate header files.
hdrs = t/''
for topic in topic_order:
signatures = t/""
for fx in topics[topic]:
if fx["header"] == "libdill.h" and fx["signature"]:
signatures |= emptyln | t/'@{signature(fx, prefix="DILL_EXPORT", code=True)}'
defines = (t/"").vjoin([t/'#define @{tp["name"]} dill_@{tp["name"]}' for tp in topics[topic]])
signatures = t/"""
if fx["protocol"]:
signatures = t/"""
if topic == "TLS protocol":
signatures = t/"""
#if !defined DILL_DISABLE_TLS
hdrs |= emptyln | t/'/* @{topic} */' | emptyln | t/'@{signatures}'
with open("libdill.tile.h", 'r') as f:
c =
with open("../libdill.h", 'w') as f:
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment