mirror of https://github.com/bsnes-emu/bsnes.git
Change docs from HTML to MD
This commit is contained in:
parent
94acbce822
commit
20fa36a7d8
10
README.md
10
README.md
|
@ -1,5 +1,4 @@
|
||||||
libco
|
# libco
|
||||||
-----
|
|
||||||
|
|
||||||
libco is a cooperative multithreading library written in C89.
|
libco is a cooperative multithreading library written in C89.
|
||||||
|
|
||||||
|
@ -21,7 +20,10 @@ It currently includes backends for:
|
||||||
* POSIX platforms (setjmp)
|
* POSIX platforms (setjmp)
|
||||||
* Windows platforms (fibers)
|
* Windows platforms (fibers)
|
||||||
|
|
||||||
License
|
See [doc/targets.md] for details.
|
||||||
=======
|
|
||||||
|
See [doc/usage.md] for documentation.
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
libco is released under the ISC license.
|
libco is released under the ISC license.
|
||||||
|
|
|
@ -1,12 +0,0 @@
|
||||||
body {
|
|
||||||
background: #333;
|
|
||||||
color: #fff;
|
|
||||||
}
|
|
||||||
|
|
||||||
code {
|
|
||||||
background: #444;
|
|
||||||
}
|
|
||||||
|
|
||||||
a {
|
|
||||||
color: #aaf;
|
|
||||||
}
|
|
|
@ -1,89 +0,0 @@
|
||||||
<html>
|
|
||||||
<head>
|
|
||||||
<title></title>
|
|
||||||
<link href="style.css" rel="stylesheet" type="text/css">
|
|
||||||
</head>
|
|
||||||
<body>
|
|
||||||
|
|
||||||
<b>Supported targets:</b><br/><br/>
|
|
||||||
|
|
||||||
Note that supported targets are only those that have been tested and confirmed
|
|
||||||
working. It is quite possible that libco will work on more processors, compilers
|
|
||||||
and operating systems than those listed below.
|
|
||||||
<hr/>
|
|
||||||
|
|
||||||
<b>libco.x86</b><br/>
|
|
||||||
Overhead: ~5x<br/>
|
|
||||||
Supported processor(s): 32-bit x86<br/>
|
|
||||||
Supported compiler(s): any<br/>
|
|
||||||
Supported operating system(s):<ul>
|
|
||||||
<li>Windows</li>
|
|
||||||
<li>Mac OS X</li>
|
|
||||||
<li>Linux</li>
|
|
||||||
<li>BSD</li>
|
|
||||||
</ul>
|
|
||||||
<hr/>
|
|
||||||
|
|
||||||
<b>libco.amd64</b><br/>
|
|
||||||
Overhead: ~10x (Windows), ~6x (all other platforms)<br/>
|
|
||||||
Supported processor(s): 64-bit amd64<br/>
|
|
||||||
Supported compiler(s): any<br/>
|
|
||||||
Supported operating system(s):<ul>
|
|
||||||
<li>Windows</li>
|
|
||||||
<li>Mac OS X</li>
|
|
||||||
<li>Linux</li>
|
|
||||||
<li>BSD</li>
|
|
||||||
</ul>
|
|
||||||
<hr/>
|
|
||||||
|
|
||||||
<b>libco.ppc</b><br/>
|
|
||||||
Overhead: ~20x<br/>
|
|
||||||
Supported processor(s): 32-bit PowerPC, 64-bit PowerPC<br/>
|
|
||||||
Supported compiler(s): GNU GCC<br/>
|
|
||||||
Supported operating system(s):<ul>
|
|
||||||
</ul>
|
|
||||||
<li>Mac OS X</li>
|
|
||||||
<li>Linux</li>
|
|
||||||
<li>BSD</li>
|
|
||||||
<li>Playstation 3</li>
|
|
||||||
</ul>
|
|
||||||
<br/>
|
|
||||||
|
|
||||||
Note: this module contains compiler flags to enable/disable FPU and Altivec
|
|
||||||
support.
|
|
||||||
|
|
||||||
<hr/>
|
|
||||||
|
|
||||||
<b>libco.fiber</b><br/>
|
|
||||||
Overhead: ~15x<br/>
|
|
||||||
Supported processor(s): Processor independent<br/>
|
|
||||||
Supported compiler(s): any<br/>
|
|
||||||
Supported operating system(s):<ul>
|
|
||||||
<li>Windows</li>
|
|
||||||
</ul>
|
|
||||||
<hr/>
|
|
||||||
|
|
||||||
<b>libco.sjlj</b><br/>
|
|
||||||
Overhead: ~30x<br/>
|
|
||||||
Supported processor(s): Processor independent<br/>
|
|
||||||
Supported compiler(s): any<br/>
|
|
||||||
Supported operating system(s):<ul>
|
|
||||||
<li>Mac OS X</li>
|
|
||||||
<li>Linux</li>
|
|
||||||
<li>BSD</li>
|
|
||||||
<li>Solaris</li>
|
|
||||||
</ul>
|
|
||||||
<hr/>
|
|
||||||
|
|
||||||
<b>libco.ucontext</b><br/>
|
|
||||||
Overhead: <b><font color="#ff0000">~300x</font></b><br/>
|
|
||||||
Supported processor(s): Processor independent<br/>
|
|
||||||
Supported compiler(s): any<br/>
|
|
||||||
Supported operating system(s):<ul>
|
|
||||||
<li>Linux</li>
|
|
||||||
<li>BSD</li>
|
|
||||||
</ul>
|
|
||||||
<hr/>
|
|
||||||
|
|
||||||
</body>
|
|
||||||
</html>
|
|
|
@ -0,0 +1,68 @@
|
||||||
|
# Supported targets
|
||||||
|
In the following lists, supported targets are only those that have been tested
|
||||||
|
and confirmed working. It is quite possible that libco will work on more
|
||||||
|
processors, compilers and operating systems than those listed below.
|
||||||
|
|
||||||
|
The "Overhead" is the cost of switching co-routines, as compared to an ordinary
|
||||||
|
C function call.
|
||||||
|
|
||||||
|
## libco.x86
|
||||||
|
* **Overhead:** ~5x
|
||||||
|
* **Supported processor(s):** 32-bit x86
|
||||||
|
*** Supported compiler(s**): any
|
||||||
|
* **Supported operating system(s):**
|
||||||
|
* Windows
|
||||||
|
* Mac OS X
|
||||||
|
* Linux
|
||||||
|
* BSD
|
||||||
|
|
||||||
|
## libco.amd64
|
||||||
|
* **Overhead:** ~10x (Windows), ~6x (all other platforms)
|
||||||
|
* **Supported processor(s):** 64-bit amd64
|
||||||
|
*** Supported compiler(s**): any
|
||||||
|
* **Supported operating system(s):**
|
||||||
|
* Windows
|
||||||
|
* Mac OS X
|
||||||
|
* Linux
|
||||||
|
* BSD
|
||||||
|
|
||||||
|
## libco.ppc
|
||||||
|
* **Overhead:** ~20x
|
||||||
|
* **Supported processor(s):** 32-bit PowerPC, 64-bit PowerPC
|
||||||
|
* **Supported compiler(s):** GNU GCC
|
||||||
|
* **Supported operating system(s):**
|
||||||
|
* Mac OS X
|
||||||
|
* Linux
|
||||||
|
* BSD
|
||||||
|
* Playstation 3
|
||||||
|
|
||||||
|
**Note:** this module contains compiler flags to enable/disable FPU and Altivec
|
||||||
|
support.
|
||||||
|
|
||||||
|
## libco.fiber
|
||||||
|
This uses Windows' "fibers" API.
|
||||||
|
* **Overhead:** ~15x
|
||||||
|
* **Supported processor(s):** Processor independent
|
||||||
|
* **Supported compiler(s):** any
|
||||||
|
* **Supported operating system(s):**
|
||||||
|
* Windows
|
||||||
|
|
||||||
|
## libco.sjlj
|
||||||
|
This uses the C standard library's `setjump`/`longjmp` APIs.
|
||||||
|
* **Overhead:** ~30x
|
||||||
|
* **Supported processor(s):** Processor independent
|
||||||
|
* **Supported compiler(s):** any
|
||||||
|
* **Supported operating system(s):**
|
||||||
|
* Mac OS X
|
||||||
|
* Linux
|
||||||
|
* BSD
|
||||||
|
* Solaris
|
||||||
|
|
||||||
|
## libco.ucontext
|
||||||
|
This uses the POSIX "ucontext" API.
|
||||||
|
* **Overhead:** ***~300x***
|
||||||
|
* **Supported processor(s):** Processor independent
|
||||||
|
* **Supported compiler(s):** any
|
||||||
|
* **Supported operating system(s):**
|
||||||
|
* Linux
|
||||||
|
* BSD
|
|
@ -1,108 +1,130 @@
|
||||||
<html>
|
# License
|
||||||
<head>
|
|
||||||
<title></title>
|
|
||||||
<link href="style.css" rel="stylesheet" type="text/css">
|
|
||||||
</head>
|
|
||||||
<body>
|
|
||||||
|
|
||||||
<b>License:</b><br/><br/>
|
|
||||||
libco is released under the ISC license.
|
libco is released under the ISC license.
|
||||||
<hr/>
|
|
||||||
|
|
||||||
<b>Foreword:</b><br/><br/>
|
# Foreword
|
||||||
libco is a cross-platform, permissively licensed implementation of
|
libco is a cross-platform, permissively licensed implementation of
|
||||||
cooperative-multithreading; a feature that is sorely lacking from the ISO C/C++
|
cooperative-multithreading; a feature that is sorely lacking from the ISO C/C++
|
||||||
standard.<br/>
|
standard.
|
||||||
|
|
||||||
The library is designed for maximum speed and portability, and not for safety or
|
The library is designed for maximum speed and portability, and not for safety or
|
||||||
features. If safety or extra functionality is desired, a wrapper API can easily
|
features. If safety or extra functionality is desired, a wrapper API can easily
|
||||||
be written to encapsulate all library functions.<br/>
|
be written to encapsulate all library functions.
|
||||||
|
|
||||||
Behavior of executing operations that are listed as not permitted below result
|
Behavior of executing operations that are listed as not permitted below result
|
||||||
in undefined behavior. They may work anyway, they may cause undesired / unknown
|
in undefined behavior. They may work anyway, they may cause undesired / unknown
|
||||||
behavior, or they may crash the program entirely.<br/>
|
behavior, or they may crash the program entirely.
|
||||||
|
|
||||||
The goal of this library was to simplify the base API as much as possible,
|
The goal of this library was to simplify the base API as much as possible,
|
||||||
implementing only that which cannot be implemented using pure C. Additional
|
implementing only that which cannot be implemented using pure C. Additional
|
||||||
functionality after this would only complicate ports of this library to new
|
functionality after this would only complicate ports of this library to new
|
||||||
platforms.
|
platforms.
|
||||||
<hr/>
|
|
||||||
|
|
||||||
<b>Porting:</b><br/><br/>
|
# Porting
|
||||||
This document is included as a reference for porting libco. Please submit any
|
This document is included as a reference for porting libco. Please submit any
|
||||||
ports you create to me, so that libco can become more useful. Please note that
|
ports you create to me, so that libco can become more useful. Please note that
|
||||||
since libco is permissively licensed, you must submit your code as a work of the
|
since libco is permissively licensed, you must submit your code as a work of the
|
||||||
public domain in order for it to be included in the official distribution.
|
public domain in order for it to be included in the official distribution.
|
||||||
|
|
||||||
Full credit will be given in the source code of the official release. Please
|
Full credit will be given in the source code of the official release. Please
|
||||||
do not bother submitting code to me under any other license -- including GPL,
|
do not bother submitting code to me under any other license -- including GPL,
|
||||||
LGPL, BSD or CC -- I am not interested in creating a library with multiple
|
LGPL, BSD or CC -- I am not interested in creating a library with multiple
|
||||||
different licenses depending on which targets are used.
|
different licenses depending on which targets are used.
|
||||||
<hr/>
|
|
||||||
|
|
||||||
<b>Synopsis:</b><br/><br/>
|
Note that there are a variety of compile-time options in `settings.h`,
|
||||||
<code>
|
so if you want to use libco on a platform where it is not supported by default,
|
||||||
typedef void* cothread_t;<br/>
|
you may be able to configure the implementation appropriately without having
|
||||||
<br/>
|
to make a whole new port.
|
||||||
cothread_t co_active();<br/>
|
|
||||||
cothread_t co_create(unsigned int heapsize, void (*coentry)(void));<br/>
|
|
||||||
void co_delete(cothread_t cothread);<br/>
|
|
||||||
void co_switch(cothread_t cothread);<br/>
|
|
||||||
</code>
|
|
||||||
<hr/>
|
|
||||||
|
|
||||||
<b>Usage:</b>
|
# Synopsis
|
||||||
<hr/>
|
```c
|
||||||
|
typedef void* cothread_t;
|
||||||
|
|
||||||
<code>typedef void* cothread_t;</code><br/><br/>
|
cothread_t co_active();
|
||||||
Handle to cothread.<br/>
|
cothread_t co_create(unsigned int heapsize, void (*coentry)(void));
|
||||||
Handle must be of type void*.<br/>
|
void co_delete(cothread_t cothread);
|
||||||
A value of null (0) indicates an uninitialized or invalid
|
void co_switch(cothread_t cothread);
|
||||||
handle, whereas a non-zero value indicates a valid handle.
|
```
|
||||||
<hr/>
|
|
||||||
|
|
||||||
<code>cothread_t co_active();</code><br/><br/>
|
# Usage
|
||||||
Return handle to current cothread. Always returns a valid handle, even when
|
## cothread_t
|
||||||
called from the main program thread.
|
```c
|
||||||
<hr/>
|
typedef void* cothread_t;
|
||||||
|
```
|
||||||
|
Handle to cothread.
|
||||||
|
|
||||||
<code>cothread_t co_derive(void* memory, unsigned int heapsize, void (*coentry)(void));</code><br/><br/>
|
Handle must be of type `void*`.
|
||||||
Initializes new cothread.</br>
|
|
||||||
This function is identical to co_create, only it attempts to use the provided
|
A value of `null` (0) indicates an uninitialized or invalid handle, whereas a non-zero value indicates a valid handle.
|
||||||
|
|
||||||
|
## co_active
|
||||||
|
```c
|
||||||
|
cothread_t co_active();
|
||||||
|
```
|
||||||
|
Return handle to current cothread.
|
||||||
|
|
||||||
|
Always returns a valid handle, even when called from the main program thread.
|
||||||
|
|
||||||
|
## co_derive
|
||||||
|
```c
|
||||||
|
cothread_t co_derive(void* memory,
|
||||||
|
unsigned int heapsize,
|
||||||
|
void (*coentry)(void));
|
||||||
|
```
|
||||||
|
Initializes new cothread.
|
||||||
|
|
||||||
|
This function is identical to `co_create`, only it attempts to use the provided
|
||||||
memory instead of allocating new memory on the heap. Please note that certain
|
memory instead of allocating new memory on the heap. Please note that certain
|
||||||
implementations (currently only Windows Fibers) cannot be created using existing
|
implementations (currently only Windows Fibers) cannot be created using existing
|
||||||
memory, and as such, this function will fail.
|
memory, and as such, this function will fail.
|
||||||
<hr/>
|
|
||||||
|
|
||||||
<code>cothread_t co_create(unsigned int heapsize, void (*coentry)(void));</code><br/><br/>
|
## co_create
|
||||||
Create new cothread.<br/>
|
```c
|
||||||
Heapsize is the amount of memory allocated for the cothread stack, specified
|
cothread_t co_create(unsigned int heapsize,
|
||||||
|
void (*coentry)(void));
|
||||||
|
```
|
||||||
|
Create new cothread.
|
||||||
|
|
||||||
|
`heapsize` is the amount of memory allocated for the cothread stack, specified
|
||||||
in bytes. This is unfortunately impossible to make fully portable. It is
|
in bytes. This is unfortunately impossible to make fully portable. It is
|
||||||
recommended to specify sizes using `n * sizeof(void*)'. It is better to err
|
recommended to specify sizes using `n * sizeof(void*)`. It is better to err
|
||||||
on the side of caution and allocate more memory than will be needed to ensure
|
on the side of caution and allocate more memory than will be needed to ensure
|
||||||
compatibility with other platforms, within reason. A typical heapsize for a
|
compatibility with other platforms, within reason. A typical heapsize for a
|
||||||
32-bit architecture is ~1MB.<br/>
|
32-bit architecture is ~1MB.
|
||||||
|
|
||||||
When the new cothread is first called, program execution jumps to coentry.
|
When the new cothread is first called, program execution jumps to coentry.
|
||||||
This function does not take any arguments, due to portability issues with
|
This function does not take any arguments, due to portability issues with
|
||||||
passing function arguments. However, arguments can be simulated by the use
|
passing function arguments. However, arguments can be simulated by the use
|
||||||
of global variables, which can be set before the first call to each cothread.<br/>
|
of global variables, which can be set before the first call to each cothread.
|
||||||
coentry() must not return, and should end with an appropriate co_switch()
|
|
||||||
statement. Behavior is undefined if entry point returns normally.<br/>
|
`coentry()` must not return, and should end with an appropriate `co_switch()`
|
||||||
|
statement. Behavior is undefined if entry point returns normally.
|
||||||
|
|
||||||
Library is responsible for allocating cothread stack memory, to free
|
Library is responsible for allocating cothread stack memory, to free
|
||||||
the user from needing to allocate special memory capable of being used
|
the user from needing to allocate special memory capable of being used
|
||||||
as program stack memory on platforms where this is required.<br/>
|
as program stack memory on platforms where this is required.
|
||||||
User is always responsible for deleting cothreads with co_delete().<br/>
|
|
||||||
Return value of null (0) indicates cothread creation failed.
|
|
||||||
<hr/>
|
|
||||||
|
|
||||||
<code>void co_delete(cothread_t cothread);</code><br/><br/>
|
User is always responsible for deleting cothreads with `co_delete()`.
|
||||||
Delete specified cothread.<br/>
|
|
||||||
Null (0) or invalid cothread handle is not allowed.<br/>
|
Return value of `null` (0) indicates cothread creation failed.
|
||||||
Passing handle of active cothread to this function is not allowed.<br/>
|
|
||||||
Passing handle of primary cothread is not allowed.
|
## co_delete
|
||||||
<hr/>
|
```c
|
||||||
|
void co_delete(cothread_t cothread);
|
||||||
|
```
|
||||||
|
Delete specified cothread.
|
||||||
|
|
||||||
|
`null` (0) or invalid cothread handle is not allowed.
|
||||||
|
|
||||||
<code>void co_switch(cothread_t cothread);</code><br/><br/>
|
|
||||||
Switch to specified cothread.<br/>
|
|
||||||
Null (0) or invalid cothread handle is not allowed.<br/>
|
|
||||||
Passing handle of active cothread to this function is not allowed.
|
Passing handle of active cothread to this function is not allowed.
|
||||||
<hr/>
|
|
||||||
|
|
||||||
</body>
|
Passing handle of primary cothread is not allowed.
|
||||||
</html>
|
|
||||||
|
## co_switch
|
||||||
|
```c
|
||||||
|
void co_switch(cothread_t cothread);
|
||||||
|
```
|
||||||
|
Switch to specified cothread.
|
||||||
|
|
||||||
|
`null` (0) or invalid cothread handle is not allowed.
|
||||||
|
|
||||||
|
Passing handle of active cothread to this function is not allowed.
|
Loading…
Reference in New Issue