gclib  307
Communications API for Galil controllers and PLCs
 All Data Structures Files Functions Variables Typedefs Macros Pages
threading.md
1 # Thread Safety {#threading}
2 
3 gclib supports multi-threaded operation with the following operational definitions.
4 
5 ### gclib is "reentrant"
6 
7 Reentrant means that a given gclib function call may be invoked in multiple threads when passed distinct arguments.
8 For example, GCommand() may be called simultaneously in different threads so long as the following arguments have
9  unique values, indicating they point to unique memory.
10 
11 * \link GCon \endlink `g`, the connection must be unique.
12 * \link GBufOut \endlink `buffer`, the writable buffer must be unique.
13 * \link GSize \endlink * `bytes_returned`, the writable value must be unique.
14 
15 
16 ### gclib is **not** "thread-safe"
17 
18 Thread safety would imply that a given gclib function call could be invoked in multiple threads when passed *the same* arguments.
19 This mode of operation **is not** supported by gclib. In other words, it is not safe to call GCommand() simultaneously in
20 different threads if any mutable arguments point to the same memory.
21 
22 In short, it is **not** safe to call GCommand() in multiple threads to the same physical connection.
23 
24 If such operation is required, it is the user's responsibility to use a mutual exclusion (mutex) or other mechanism to protect memory.
25 
26 ### Multi-threaded access to the same connection with gcaps
27 
28 @ref gcaps provides a multiplexing capability to Galil hardware. When using gcaps,
29 it is therefore safe to call GCommand() in multiple threads to the *same physical connection* (though not the same \link GCon \endlink value).
30 gclib can connect multiple times to the same Galil connection through gcaps. Because the \link GCon \endlink variable is unique, the
31 reentrant capability of gclib can be used to communicate to the same physical connection through gcaps.
32