00001 # Thread Safety {#threading}
00002
00003 gclib supports multi-threaded operation with the following operational definitions.
00004
00005 ### gclib is "reentrant"
00006
00007 Reentrant means that a given gclib function call may be invoked in multiple threads when passed distinct arguments.
00008 For example, GCommand() may be called simultaneously in different threads so long as the following arguments have
00009 unique values, indicating they point to unique memory.
00010
00011 * \link GCon \endlink `g`, the connection must be unique.
00012 * \link GBufOut \endlink `buffer`, the writable buffer must be unique.
00013 * \link GSize \endlink * `bytes_returned`, the writable value must be unique.
00014
00015
00016 ### gclib is **not** "thread-safe"
00017
00018 Thread safety would imply that a given gclib function call could be invoked in multiple threads when passed *the same* arguments.
00019 This mode of operation **is not** supported by gclib. In other words, it is not safe to call GCommand() simultaneously in
00020 different threads if any mutable arguments point to the same memory.
00021
00022 In short, it is **not** safe to call GCommand() in multiple threads to the same physical connection.
00023
00024 If such operation is required, it is the user's responsibility to use a mutual exclusion (mutex) or other mechanism to protect memory.
00025
00026 ### Multi-threaded access to the same connection with gcaps
00027
00028 The Galil Controller Asynchronous Proxy Server (gcaps) provides a multiplexing capability to Galil hardware. When using gcaps,
00029 it is therefore safe to call GCommand() in multiple threads to the *same physical connection* (though not the same \link GCon \endlink value).
00030 gclib can connect multiple times to the same Galil connection through gcaps. Because the \link GCon \endlink variable is unique, the
00031 reentrant capability of gclib can be used to communicate to the same physical connection through gcaps.
00032
