Multi-Threaded Apps and the VL

By Chris Pirazzi.

If your app has more than one thread (due to either a sproc(2) or a pthread_create(3P)), and you could potentially manipulate VL objects from more than one thread at a time, make sure you follow these rules.

General Rules

Call the set of threads in your app which share either address space, file descriptors, or both a "process share group."

When you make VL calls, you pass in VL objects such as VLServer, VLPath, VLNode, VLBuffer, etc. All of the objects hang off of the VLServer. You cannot create any of the other objects without first creating a VLServer. All of the arguments to a VL call must derive from the same VLServer.

In a given process share group, there may only be one VL call executing at a time whose arguments derive from a given VLServer. This even includes VL calls which do not explicitly take a VLServer as an argument (for example, vlBufferAdvise).

You may use objects derived from a given VLServer in any number of threads, as long as you make the use in each thread mutually exclusive of a use in any of the other threads via some locking scheme (such as usnewsema(3P) or pthread_mutex_init(3P)).

This has been true since the earliest days (vino and ev1). Violating this rule will result in intermittent core dumps on all video platforms. Because O2 video does not use a daemon (videod) like the other video systems, you may find that violating this rule produces core dumps more often on O2, because in the deamon-based video scheme, the unix-domain-socket to videod sometimes serialized operations for the user (note sometimes).

If you want to make uncoordinated VL calls from more than one thread, you will need more than one VLServer.

A VLServer Has Only One Buffering API

When you create a VLServer, that server is in a neutral state. As soon as you use an API call from the classic, O2, or cross-platform buffering API (see What Are the SGI Video-Related Libraries? for more info), that VLServer can then only be used with that buffering API, from any thread. So if you want to use two buffering APIs from the same process share group, you will need two VLServers.

Caveat: VL Error State

The VL's error state, returned by vlGetErrno(3dm), is currently share-group-global and is not per-VLServer. So if you have a VL call using one VLServer in one thread, executing simultaneously with a VL call using another VLServer in another thread, both calls will try and set the error state returned by vlGetErrno(3dm). This is a known problem which will be fixed at some point. The vlGetErrno(3dm) call should be global only to the thread, not the entire process share group.