README.md 3.84 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

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. At this moment it only works in asynchronous mode.
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
64
65
66
67
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 '/'

`[writer]/->[reader]` means no synchronization
`[writer].->[reader]` means the reader waits for new data from the writer
`[writer]^->[reader]` means the writer waits for the reader to read and acknowledge the data
`[writer]:->[reader]` 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