README.md 3.79 KB
Newer Older
Arnaud Blanchard's avatar
Arnaud Blanchard committed
1 2
BLC channel
===========
Arnaud Blanchard's avatar
Arnaud Blanchard committed
3

4 5 6
- Copyright : [ETIS](http://www.etis.ensea.fr/neurocyber) - ENSEA, University of Cergy-Pontoise, CNRS (2011-2016)  
- Author    : [Arnaud Blanchard](http://arnaudblanchard.thoughtsheet.com)  
- Licence   : [CeCILL v2.1](http://www.cecill.info/licences/Licence_CeCILL_V2-en.html)  
Arnaud Blanchard's avatar
Arnaud Blanchard committed
7

Arnaud Blanchard's avatar
Arnaud Blanchard committed
8
Functions to easily share data through shared memory (shm_... functions). It is the fastest, and the more econom in memory ( no copy in each process ), way to share informtation between processes.
Arnaud Blanchard's avatar
Arnaud Blanchard committed
9 10 11 12 13 14

Example
=======

For exemple you create a channel in one program to write data:

15 16
```c++
//Creating shared called '/my_channel_name', this program will write on it, it is char ('INT8') with no specific format ('NDEF') of dimension 1 (vector) of 32 elements.
Arnaud Blanchard's avatar
Arnaud Blanchard committed
17
    
18 19 20
blc_channel my_channel.create("/my_channel_name", BLC_CHANNEL_WRITE, 'INT8', 'NDEF', 1, 32);
snprintf(my_channel.chars, 32, "Hello world !\n");
```
Arnaud Blanchard's avatar
Arnaud Blanchard committed
21 22
    
and read this data in another program:
Arnaud Blanchard's avatar
amend  
Arnaud Blanchard committed
23

24 25
```c++
//Opening shared memory called '/my_channel_name', this program will only read it.
Arnaud Blanchard's avatar
Arnaud Blanchard committed
26

27 28 29
blc_channel my_receiving_channel.open("/my_channel_name", BLC_CHANNEL_READ);
printf("%s", my_receiving_channel.chars);
```
Arnaud Blanchard's avatar
Arnaud Blanchard committed
30 31 32
     
The second program prints 'Hello world !'.

Arnaud Blanchard's avatar
Arnaud Blanchard committed
33 34
For more details about **type**, **format** and **dimensions** see [blc_array](https://promethe.u-cergy.fr/blibs/blc_core/blob/master/README.md#blc_array)

Arnaud Blanchard's avatar
Arnaud Blanchard committed
35 36 37 38
Demo
====

`blc_channel/demo.sh` launches two processes. 
Arnaud Blanchard's avatar
Arnaud Blanchard committed
39

Arnaud Blanchard's avatar
Arnaud Blanchard committed
40 41
- `t_channel_reader` reading each second the content of '/channel_example' and printing it.
- `t_channel_writer` waiting for the user to enter text and filing the channel '/channel_example' with this text.  Each second the reader will print this text. 
Arnaud Blanchard's avatar
Arnaud Blanchard committed
42 43 44 45 46 47

Press 'q' to quit.

Details
=======

Arnaud Blanchard's avatar
Arnaud Blanchard committed
48
The information about the properties of the blc_channels (type, format, sizes) is stored in a special file: **`/tmp/blc_channels.txt`**. You are not suppose to use it but you can check at anytime the status of the blc_channels using **`blc_channels`**.
Arnaud Blanchard's avatar
Arnaud Blanchard committed
49 50 51

You will see all the existing blc_channels, the process reading or writing and the possibility to destroy channels.

Arnaud Blanchard's avatar
Arnaud Blanchard committed
52
On Linux we can see and manipulate a virtual file containing this memory in **`/run/shm/<name of your shared memory>`**, on OSX you cannot but anyway it is only used for debug.
Arnaud Blanchard's avatar
Arnaud Blanchard committed
53

54 55 56 57 58 59 60 61 62 63
Synchronisation
===============

Two semaphores associated to the shared memory are created:

- `blc_channle<id>_new_data0` which indicates that new data is available on the shared memory
- `blc_channle<id>_ack_data0` which acknowledges that the data has been read

Proccesses which do not consider synchronisation use starting char '/'

Arnaud Blanchard's avatar
Arnaud Blanchard committed
64 65 66
- `/channel_name` means no synchronization
- `.channel_name` means the reader waits for new data from the writer
- `^channel_name` means the writer waits for the reader to read and acknowledge the data
Arnaud Blanchard's avatar
Arnaud Blanchard committed
67
- `:channel_name` (default)  means both direction synchronization. The writer waits for acknowledgement and the reader wait for new data from the writer.
68 69 70 71 72 73 74 75 76 77 78 79 80 81 82

While opening a channel
-----------------------

In synchronous mode, we assume there is only one reader and writter at a time

- **new 0, ack 1**: The data has been read, the receiver is ready
- **new 1, ack 0**: New data is ready for reading
- **new 0, ack 0**(1): The data is being read or written. This is a scenario where you do not know if you have to wait or if the channel was badly closed
- **new 1, ack 1**(2): The new data has not been read yet. This must not happen as the risk is that you can read and write at the same time

At the initialisation, when a channel is created, **ack** is set to 1


If you have a problem, case (1) you can use the tools blc_channels to manually unlock **ack** or **new**. 
Arnaud Blanchard's avatar
amend  
Arnaud Blanchard committed
83 84 85 86

C/C++ documentation
===================

Arnaud Blanchard's avatar
Arnaud Blanchard committed
87
To see the documentation for C++, execute : `./doc_api blibs/blc_channel` in your blaar directory. Add `-c` option if you want the plain C api.
Arnaud Blanchard's avatar
amend  
Arnaud Blanchard committed
88 89