Contexts

It is possible that libusbx may be used simultaneously from two independent libraries linked into the same executable.

For example, if your application has a plugin-like system which allows the user to dynamically load a range of modules into your program, it is feasible that two independently developed modules may both use libusbx.

libusbx is written to allow for these multiple user scenarios. The two "instances" of libusbx will not interfere: libusb_set_debug() calls from one user will not affect the same settings for other users, other users can continue using libusbx after one of them calls libusb_exit(), etc.

This is made possible through libusbx's context concept. When you call libusb_init(), you are (optionally) given a context. You can then pass this context pointer back into future libusbx functions.

In order to keep things simple for more simplistic applications, it is legal to pass NULL to all functions requiring a context pointer (as long as you're sure no other code will attempt to use libusbx from the same process). When you pass NULL, the default context will be used. The default context is created the first time a process calls libusb_init() when no other context is alive. Contexts are destroyed during libusb_exit().

The default context is reference-counted and can be shared. That means that if libusb_init(NULL) is called twice within the same process, the two users end up sharing the same context. The deinitialization and freeing of the default context will only happen when the last user calls libusb_exit(). In other words, the default context is created and initialized when its reference count goes from 0 to 1, and is deinitialized and destroyed when its reference count goes from 1 to 0.

You may be wondering why only a subset of libusbx functions require a context pointer in their function definition. Internally, libusbx stores context pointers in other objects (e.g. libusb_device instances) and hence can infer the context from those objects.