move README to README.md

This commit is contained in:
David du Colombier 2015-07-29 23:03:08 +02:00
parent 798c8c6df8
commit 1bd5583c53

View File

@ -1,3 +1,9 @@
Libtask: a Coroutine Library for C and Unix
===========================================
[![Build Status](https://drone.io/github.com/0intro/libtask/status.png)](https://drone.io/github.com/0intro/libtask/latest)
[![Coverity Scan Status](https://scan.coverity.com/projects/5467/badge.svg)](https://scan.coverity.com/projects/5467)
Libtask is a simple coroutine library. It runs on Linux (ARM, MIPS, and x86), Libtask is a simple coroutine library. It runs on Linux (ARM, MIPS, and x86),
FreeBSD (x86), OS X (PowerPC x86, and x86-64), and SunOS Solaris (Sparc), FreeBSD (x86), OS X (PowerPC x86, and x86-64), and SunOS Solaris (Sparc),
and is easy to port to other systems. and is easy to port to other systems.
@ -12,7 +18,8 @@ the CPU. Most of the functions provided in task.h do have
the possibility of going to sleep. Programs using the task the possibility of going to sleep. Programs using the task
functions should #include <task.h>. functions should #include <task.h>.
--- Basic task manipulation Basic task manipulation
-----------------------
int taskcreate(void (*f)(void *arg), void *arg, unsigned int stacksize); int taskcreate(void (*f)(void *arg), void *arg, unsigned int stacksize);
@ -23,7 +30,7 @@ void tasksystem(void);
Mark the current task as a "system" task. These are ignored Mark the current task as a "system" task. These are ignored
for the purposes of deciding the program is done running for the purposes of deciding the program is done running
(see taskexit next). (see taskexit next).
void taskexit(int status); void taskexit(int status);
Exit the current task. If this is the last non-system task, Exit the current task. If this is the last non-system task,
@ -38,7 +45,7 @@ void taskmain(int argc, char *argv[]);
Write this function instead of main. Libtask provides its own main. Write this function instead of main. Libtask provides its own main.
int taskyield(void); int taskyield(void);
Explicitly give up the CPU. The current task will be scheduled Explicitly give up the CPU. The current task will be scheduled
again once all the other currently-ready tasks have a chance again once all the other currently-ready tasks have a chance
to run. Returns the number of other tasks that ran while the to run. Returns the number of other tasks that ran while the
@ -65,16 +72,16 @@ void needstack(int n);
void taskname(char*, ...); void taskname(char*, ...);
Takes an argument list like printf. Sets the current task's name. Takes an argument list like printf. Sets the current task's name.
char* taskgetname(void); char* taskgetname(void);
Returns the current task's name. Is the actual buffer; do not free. Returns the current task's name. Is the actual buffer; do not free.
void taskstate(char*, ...); void taskstate(char*, ...);
char* taskgetstate(void); char* taskgetstate(void);
Like taskname and taskgetname but for the task state. Like taskname and taskgetname but for the task state.
When you send a tasked program a SIGQUIT (or SIGINFO, on BSD) When you send a tasked program a SIGQUIT (or SIGINFO, on BSD)
it will print a list of all its tasks and their names and states. it will print a list of all its tasks and their names and states.
This is useful for debugging why your program isn't doing anything! This is useful for debugging why your program isn't doing anything!
@ -83,10 +90,11 @@ unsigned int taskid(void);
Return the unique task id for the current task. Return the unique task id for the current task.
--- Non-blocking I/O Non-blocking I/O
----------------
There is a small amount of runtime support for non-blocking I/O There is a small amount of runtime support for non-blocking I/O
on file descriptors. on file descriptors.
int fdnoblock(int fd); int fdnoblock(int fd);
@ -116,10 +124,11 @@ void fdwait(int fd, int rw);
anything else means just exceptional conditions (hang up, etc.) anything else means just exceptional conditions (hang up, etc.)
The 'r' and 'w' also wake up for exceptional conditions. The 'r' and 'w' also wake up for exceptional conditions.
--- Network I/O Network I/O
-----------
These are convenient packaging of the ugly Unix socket routines. These are convenient packaging of the ugly Unix socket routines.
They can all put the current task to sleep during the call. They can all put the current task to sleep during the call.
int netannounce(int proto, char *address, int port) int netannounce(int proto, char *address, int port)
@ -128,7 +137,7 @@ int netannounce(int proto, char *address, int port)
string version of a host name or IP address. If address is null, string version of a host name or IP address. If address is null,
then announce binds to the given port on all available interfaces. then announce binds to the given port on all available interfaces.
Returns a fd to use with netaccept. Returns a fd to use with netaccept.
Examples: netannounce(TCP, "localhost", 80) or Examples: netannounce(TCP, "localhost", 80) or
netannounce(TCP, "127.0.0.1", 80) or netannounce(TCP, 0, 80). netannounce(TCP, "127.0.0.1", 80) or netannounce(TCP, 0, 80).
int netaccept(int fd, char *server, int *port) int netaccept(int fd, char *server, int *port)
@ -141,7 +150,7 @@ int netaccept(int fd, char *server, int *port)
Example: Example:
char server[46]; char server[46];
int port; int port;
if(netaccept(fd, server, &port) >= 0) if(netaccept(fd, server, &port) >= 0)
printf("connect from %s:%d", server, port); printf("connect from %s:%d", server, port);
@ -154,14 +163,16 @@ int netdial(int proto, char *name, int port)
Example: netdial(TCP, "www.google.com", 80) Example: netdial(TCP, "www.google.com", 80)
or netdial(TCP, "18.26.4.9", 80) or netdial(TCP, "18.26.4.9", 80)
--- Time Time
----
unsigned int taskdelay(unsigned int ms) unsigned int taskdelay(unsigned int ms)
Put the current task to sleep for approximately ms milliseconds. Put the current task to sleep for approximately ms milliseconds.
Return the actual amount of time slept, in milliseconds. Return the actual amount of time slept, in milliseconds.
--- Example programs Example programs
----------------
In this directory, tcpproxy.c is a simple TCP proxy that illustrates In this directory, tcpproxy.c is a simple TCP proxy that illustrates
most of the above. You can run most of the above. You can run
@ -175,16 +186,18 @@ Other examples are:
httpload.c - simple HTTP load generator httpload.c - simple HTTP load generator
testdelay.c - test taskdelay() testdelay.c - test taskdelay()
--- Building Building
--------
To build, run make. You can run make install to copy task.h and To build, run make. You can run make install to copy task.h and
libtask.a to the appropriate places in /usr/local. Then you libtask.a to the appropriate places in /usr/local. Then you
should be able to just link with -ltask in your programs should be able to just link with -ltask in your programs
that use it. that use it.
On SunOS Solaris machines, run makesun instead of just make. On SunOS Solaris machines, run makesun instead of just make.
--- Contact Info Contact Info
------------
Please email me with questions or problems. Please email me with questions or problems.
@ -192,8 +205,8 @@ Russ Cox
rsc@swtch.com rsc@swtch.com
--- Stuff you probably won't use at first --- Stuff you probably won't use at first but might want to know about eventually
--- but might want to know about eventually --- -----------------------------------------------------------------------------
void tasksleep(Rendez*); void tasksleep(Rendez*);
int taskwakeup(Rendez*); int taskwakeup(Rendez*);
@ -203,7 +216,7 @@ int taskwakeupall(Rendez*);
just allocating memory for it (or putting it in another structure) just allocating memory for it (or putting it in another structure)
and then zeroing the memory. Tasksleep(r) 'sleeps on r', giving and then zeroing the memory. Tasksleep(r) 'sleeps on r', giving
up the CPU. Multiple tasks can sleep on a single Rendez. up the CPU. Multiple tasks can sleep on a single Rendez.
When another task comes along and calls taskwakeup(r), When another task comes along and calls taskwakeup(r),
the first task sleeping on r (if any) will be woken up. the first task sleeping on r (if any) will be woken up.
Taskwakeupall(r) wakes up all the tasks sleeping on r. Taskwakeupall(r) wakes up all the tasks sleeping on r.
They both return the actual number of tasks awakened. They both return the actual number of tasks awakened.
@ -214,7 +227,7 @@ void qlock(QLock*);
int canqlock(QLock*); int canqlock(QLock*);
void qunlock(QLock*); void qunlock(QLock*);
You probably won't need locks because of the cooperative You probably won't need locks because of the cooperative
scheduling, but if you do, here are some. You can make a new scheduling, but if you do, here are some. You can make a new
QLock by just declaring it and zeroing the memory. QLock by just declaring it and zeroing the memory.
Calling qlock will give up the CPU if the lock is held by someone else. Calling qlock will give up the CPU if the lock is held by someone else.
@ -233,7 +246,7 @@ void wunlock(RWLock*);
RWLocks are reader-writer locks. Any number of readers RWLocks are reader-writer locks. Any number of readers
can lock them at once, but only one writer at a time. can lock them at once, but only one writer at a time.
If a writer is holding it, there can't be any readers. If a writer is holding it, there can't be any readers.
Channel *chancreate(int, int); Channel *chancreate(int, int);
etc. etc.
@ -241,11 +254,9 @@ etc.
Channels are buffered communication pipes you can Channels are buffered communication pipes you can
use to send messages between tasks. Some people like use to send messages between tasks. Some people like
doing most of the inter-task communication using channels. doing most of the inter-task communication using channels.
For details on channels see the description of channels in For details on channels see the description of channels in
http://swtch.com/usr/local/plan9/man/man3/thread.html and http://swtch.com/usr/local/plan9/man/man3/thread.html and
http://swtch.com/~rsc/thread/ http://swtch.com/~rsc/thread/
and also the example program primes.c, which implements and also the example program primes.c, which implements
a concurrent prime sieve. a concurrent prime sieve.