Please consider a donation to the Higher Intellect project. See https://preterhuman.net/donate.php or the Donate to Higher Intellect page for more info.

Multi-Threaded Apps and the VL

From Higher Intellect Vintage Wiki
Jump to navigation Jump to search

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 ev1, ev3, vino, and sirius video systems use a daemon (videod) and O2 video does not, 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.

The O2 Buffering API

On the O2, there is a further constraint. The O2 VL has two ways of accessing video data: traditional VLBuffers (the classic buffering API) and DMbuffers (the O2 buffering API). Check out What Are the SGI Video-Related Libraries for more information about that. When you create a VLServer, that server is in a neutral state. As soon as you use an API call from the classic buffering API or the O2 buffering API, that VLServer can then only be used with that buffering API, from any thread. So if you want to use the classic buffering API and the O2 buffering API 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 anohther 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.