v12 API: add global lock and unlock

Author: pinterf

avs_core/core/CompatEnvironment.h

@@ -295,6 +295,12 @@ class IScriptEnvironment_AvsPreV11C {
   virtual int __stdcall propGetDataTypeHint(const AVSMap* map, const char* key, int index, int* error) = 0; // returns AVSPropDataTypeHint
   virtual int __stdcall propSetDataH(AVSMap* map, const char* key, const char* d, int length, int type, int append) = 0;
 
+  // V12
+  // New Global Lock API for cross-plugin synchronization.
+  // Plugins must ensure these calls are balanced (acquire followed by release),
+  virtual bool __stdcall AcquireGlobalLock(const char* name) = 0;
+  virtual void __stdcall ReleaseGlobalLock(const char* name) = 0;
+
 }; // end class IScriptEnvironment_AvsPreV11C. Order is important.
 
 #endif // _AVS_COMPATENVIRONMENT_H_INCLUDED

avs_core/core/InternalEnvironment.h

@@ -202,6 +202,10 @@ class InternalEnvironment :
   virtual int __stdcall propGetDataTypeHint(const AVSMap* map, const char* key, int index, int* error) = 0; /* returns AVSPropDataTypeHint */
   virtual int __stdcall propSetDataH(AVSMap* map, const char* key, const char* d, int length, int type, int append) = 0;
 
+  // V12
+  virtual bool __stdcall AcquireGlobalLock(const char* name) = 0;
+  virtual void __stdcall ReleaseGlobalLock(const char* name) = 0;
+
   // IScriptEnvironment2
   virtual bool __stdcall LoadPlugin(const char* filePath, bool throwOnError, AVSValue *result) = 0;
   virtual void __stdcall AddAutoloadDir(const char* dirPath, bool toFront) = 0;

avs_core/core/avisynth.cpp

@@ -88,6 +88,7 @@
 #include <clocale>
 #include <cmath>
 #include <limits>
+#include <set>
 
 #include "FilterGraph.h"
 #include "DeviceManager.h"
@@ -97,6 +98,83 @@
   #define YieldProcessor() __nop(void)
 #endif
 
+/* Global Lock Manager */
+class GlobalLockManager
+{
+public:
+  // Get a named mutex. If it doesn't exist, it's created.
+  static std::mutex& get_mutex(const std::string& name);
+
+  // Track which environments hold which locks for cleanup.
+  static void acquire_lock_for_env(const std::string& name, ScriptEnvironment* env);
+  static void release_lock_for_env(const std::string& name, ScriptEnvironment* env);
+
+  // Called when an IScriptEnvironment is destroyed.
+  static void on_environment_exit(ScriptEnvironment* env);
+
+private:
+  GlobalLockManager() = delete;
+  ~GlobalLockManager() = delete;
+
+  static std::map<std::string, std::unique_ptr<std::mutex>> s_namedMutexes;
+  static std::mutex s_mutexMapLock; // Protects s_namedMutexes
+
+  static std::map<ScriptEnvironment*, std::set<std::string>> s_envToHeldLocks;
+  static std::mutex s_envLocksMapLock; // Protects s_envToHeldLocks
+};
+
+std::map<std::string, std::unique_ptr<std::mutex>> GlobalLockManager::s_namedMutexes;
+std::mutex GlobalLockManager::s_mutexMapLock;
+std::map<ScriptEnvironment*, std::set<std::string>> GlobalLockManager::s_envToHeldLocks;
+std::mutex GlobalLockManager::s_envLocksMapLock;
+
+std::mutex& GlobalLockManager::get_mutex(const std::string& name)
+{
+  std::lock_guard<std::mutex> lock(s_mutexMapLock);
+  if (s_namedMutexes.find(name) == s_namedMutexes.end())
+  {
+    s_namedMutexes[name] = std::make_unique<std::mutex>();
+  }
+  return *s_namedMutexes[name];
+}
+
+void GlobalLockManager::acquire_lock_for_env(const std::string& name, ScriptEnvironment* env)
+{
+  std::lock_guard<std::mutex> envLock(s_envLocksMapLock);
+  s_envToHeldLocks[env].insert(name);
+}
+
+void GlobalLockManager::release_lock_for_env(const std::string& name, ScriptEnvironment* env)
+{
+  std::lock_guard<std::mutex> envLock(s_envLocksMapLock);
+  if (s_envToHeldLocks.count(env))
+  {
+    s_envToHeldLocks[env].erase(name);
+    if (s_envToHeldLocks[env].empty())
+    {
+      s_envToHeldLocks.erase(env);
+    }
+  }
+}
+
+void GlobalLockManager::on_environment_exit(ScriptEnvironment* env)
+{
+  std::lock_guard<std::mutex> envLock(s_envLocksMapLock);
+  auto it = s_envToHeldLocks.find(env);
+  if (it != s_envToHeldLocks.end())
+  {
+    // Note: The actual mutexes are not unlocked here, only the tracking is cleared.
+    // A truly stuck mutex requires more complex solutions (e.g., timed_mutex with recovery,
+    // or ensuring threads exit gracefully). For Avisynth's use case, clearing the tracking
+    // is important to prevent memory leaks in the map.
+
+    // If it tried to call unlock() on a mutex held by another (potentially crashed) thread,
+    // that would lead to undefined behavior.By simply removing the tracking entry,
+    // we avoid this dangerous operation.
+    s_envToHeldLocks.erase(it);
+  }
+}
+
 extern const AVSFunction Audio_filters[],
                          Combine_filters[],
                          Convert_filters[],
@@ -779,6 +857,8 @@ class ScriptEnvironment {
   PVideoFrame Subframe(PVideoFrame src, int rel_offset, int new_pitch, int new_row_size, int new_height);
   int SetMemoryMax(int mem);
   int SetWorkingDir(const char* newdir);
+  bool AcquireGlobalLock(const char* name);
+  void ReleaseGlobalLock(const char* name);
   AVSC_CC ~ScriptEnvironment();
   void* ManageCache(int key, void* data);
   bool PlanarChromaAlignment(IScriptEnvironment::PlanarChromaAlignmentMode key);
@@ -1911,6 +1991,14 @@ class ThreadScriptEnvironment : public InternalEnvironment
     return core->SetWorkingDir(newdir);
   }
 
+  bool __stdcall AcquireGlobalLock(const char* name) {
+    return core->AcquireGlobalLock(name);
+  }
+
+  void __stdcall ReleaseGlobalLock(const char* name) {
+    core->ReleaseGlobalLock(name);
+  }
+
   void* __stdcall ManageCache(int key, void* data)
   {
     if (
@@ -2602,6 +2690,8 @@ ScriptEnvironment::~ScriptEnvironment() {
   // give every one their last wish.
   at_exit.Execute(threadEnv.get());
 
+  GlobalLockManager::on_environment_exit(this); // V12
+
   delete thread_pool;
 
   tls->var_table.Clear();
@@ -5567,6 +5657,25 @@ int ScriptEnvironment::SetMemoryMax(AvsDeviceType type, int index, int mem)
   return Devices->GetDevice(type, index)->SetMemoryMax(mem);
 }
 
+bool ScriptEnvironment::AcquireGlobalLock(const char* name)
+{
+  if (!name) return false;
+  std::string lock_name(name);
+  std::mutex& mtx = GlobalLockManager::get_mutex(lock_name);
+  mtx.lock(); // Blocks until lock is acquired.
+  GlobalLockManager::acquire_lock_for_env(lock_name, this); // Track for cleanup.
+  return true;
+}
+
+void ScriptEnvironment::ReleaseGlobalLock(const char* name)
+{
+  if (!name) return;
+  std::string lock_name(name);
+  std::mutex& mtx = GlobalLockManager::get_mutex(lock_name);
+  GlobalLockManager::release_lock_for_env(lock_name, this); // Untrack.
+  mtx.unlock();
+}
+
 PVideoFrame ScriptEnvironment::GetOnDeviceFrame(const PVideoFrame& src, Device* device)
 {
   typedef int diff_t;

avs_core/core/avisynth.def

@@ -165,3 +165,5 @@ EXPORTS
   avs_val_is_array = _avs_val_is_array@8
   avs_val_is_error = _avs_val_is_error@8
 
+  avs_acquire_global_lock = _avs_acquire_global_lock@8
+  avs_release_global_lock = _avs_release_global_lock@8

avs_core/core/avisynth_c.cpp

@@ -1513,6 +1513,33 @@ int AVSC_CC avs_set_working_dir(AVS_ScriptEnvironment * p, const char* newdir)
   }
 }
 
+// V12
+extern "C"
+int AVSC_CC avs_acquire_global_lock(AVS_ScriptEnvironment* p, const char* name)
+{
+  p->error = 0;
+  try {
+    return p->env->AcquireGlobalLock(name) ? 1 : 0;
+  }
+  catch (const AvisynthError& err) {
+    p->error = err.msg;
+    return 0;
+  }
+}
+
+// V12
+extern "C"
+void AVSC_CC avs_release_global_lock(AVS_ScriptEnvironment* p, const char* name)
+{
+  p->error = 0;
+  try {
+    p->env->ReleaseGlobalLock(name);
+  }
+  catch (const AvisynthError& err) {
+    p->error = err.msg;
+  }
+}
+
 // Interface V8. See AVS_AEP_xxx enums
 extern "C"
 size_t AVSC_CC avs_get_env_property(AVS_ScriptEnvironment * p, int avs_aep_prop)

avs_core/include/avisynth.h

@@ -54,6 +54,7 @@
 //           - New propSetDataH, like propSetData but with optional data type hint (byte/string)
 //             (VSAPI4: mapSetData, our propSetData became VSAPI4: mapSetData3)
 // 20250415  V11.1 Fix AVS_Value 64 bit data member declaration for 64-bit non Intel (other than X86_X64) systems.
+// 20250601  V12 Global lock aquire and release: AcquireGlobalLock, ReleaseGlobalLock
 
 // http://avisynth.nl
 
@@ -90,8 +91,8 @@
 // graphical user interfaces.
 
 
-#ifndef __AVISYNTH_11_H__
-#define __AVISYNTH_11_H__
+#ifndef __AVISYNTH_12_H__
+#define __AVISYNTH_12_H__
 
 #include "avs/config.h"
 #include "avs/capi.h"
@@ -124,8 +125,8 @@ enum AvsVersion {
   AVISYNTH_CLASSIC_INTERFACE_VERSION_25 = 3,
   AVISYNTH_CLASSIC_INTERFACE_VERSION_26BETA = 5,
   AVISYNTH_CLASSIC_INTERFACE_VERSION = 6,
-  AVISYNTH_INTERFACE_VERSION = 11,
-  AVISYNTHPLUS_INTERFACE_BUGFIX_VERSION = 1 // reset to zero whenever the normal interface version bumps
+  AVISYNTH_INTERFACE_VERSION = 12,
+  AVISYNTHPLUS_INTERFACE_BUGFIX_VERSION = 0 // reset to zero whenever the normal interface version bumps
 };
 
 /* Compiler-specific crap */
@@ -1714,6 +1715,12 @@ class IScriptEnvironment {
   virtual int __stdcall propGetDataTypeHint(const AVSMap* map, const char* key, int index, int* error) = 0; // returns AVSPropDataTypeHint
   virtual int __stdcall propSetDataH(AVSMap* map, const char* key, const char* d, int length, int type, int append) = 0;
 
+  // V12
+  // New Global Lock API for cross-plugin synchronization.
+  // Plugins must ensure these calls are balanced (acquire followed by release),
+  virtual bool __stdcall AcquireGlobalLock(const char* name) = 0;
+  virtual void __stdcall ReleaseGlobalLock(const char* name) = 0;
+
 }; // end class IScriptEnvironment. Order is important. Avoid overloads with the same name.
 
 
@@ -1939,6 +1946,9 @@ class INeoEnv {
   virtual void* __stdcall Allocate(size_t nBytes, size_t alignment, AvsAllocType type) = 0;
   virtual void __stdcall Free(void* ptr) = 0;
 
+  virtual bool __stdcall AcquireGlobalLock(const char* name) = 0;
+  virtual void __stdcall ReleaseGlobalLock(const char* name) = 0;
+
   virtual char* __stdcall SaveString(const char* s, int length = -1) = 0;
   virtual char* __stdcall SaveString(const char* s, int length, bool escape) = 0;
   virtual char* Sprintf(const char* fmt, ...) = 0;
@@ -2031,4 +2041,4 @@ AVSC_API(IScriptEnvironment2*, CreateScriptEnvironment2)(int version = AVISYNTH_
 
 #pragma pack(pop)
 
-#endif //__AVISYNTH_11_H__
+#endif //__AVISYNTH_12_H__

avs_core/include/avisynth_c.h

@@ -130,6 +130,7 @@
 //         New avs_add_func_r: alternative avs_add_func which returns the result in a byref parameter
 //         New AVS_ApplyFuncR type
 // 20250415 V11.1 Fix AVS_Value 64 bit data member declaration for 64-bit non Intel (other than X86_X64) systems.
+// 20250601 V12 Global lock acquire and release: avs_acquire_global_lock, avs_release_global_lock
 
 // Notes.
 // Choose either method:
@@ -160,11 +161,11 @@
 // Constants
 //
 
-#ifndef __AVISYNTH_11_H__
+#ifndef __AVISYNTH_12_H__
 enum {
   AVISYNTH_INTERFACE_CLASSIC_VERSION = 6,
-  AVISYNTH_INTERFACE_VERSION = 11,
-  AVISYNTHPLUS_INTERFACE_BUGFIX_VERSION = 1 // reset to zero whenever the normal interface version bumps
+  AVISYNTH_INTERFACE_VERSION = 12,
+  AVISYNTHPLUS_INTERFACE_BUGFIX_VERSION = 0 // reset to zero whenever the normal interface version bumps
 };
 #endif
 
@@ -1329,6 +1330,16 @@ AVSC_API(int, avs_set_memory_max)(AVS_ScriptEnvironment *, int mem);
 
 AVSC_API(int, avs_set_working_dir)(AVS_ScriptEnvironment *, const char * newdir);
 
+// V12
+// Acquire a global named lock.
+// 'env' is the environment handle, 'name' is the lock identifier (e.g., "fftw").
+// Returns 1 on success, 0 on failure.
+AVSC_API(int, avs_acquire_global_lock)(AVS_ScriptEnvironment *, const char* name);
+// V12
+// Release a global named lock.
+// 'env' is the environment handle, 'name' is the lock identifier.
+AVSC_API(void, avs_release_global_lock)(AVS_ScriptEnvironment *, const char* name);
+
 // avisynth.dll exports this; it's a way to use it as a library, without
 // writing an AVS script or without going through AVIFile.
 AVSC_API(AVS_ScriptEnvironment *, avs_create_script_environment)(int version);
@@ -1651,6 +1662,9 @@ struct AVS_Library {
   AVSC_DECLARE_FUNC(avs_val_is_string);
   AVSC_DECLARE_FUNC(avs_val_is_array);
   AVSC_DECLARE_FUNC(avs_val_is_error);
+  // V12
+  AVSC_DECLARE_FUNC(avs_acquire_global_lock);
+  AVSC_DECLARE_FUNC(avs_release_global_lock);
 };
 
 #undef AVSC_DECLARE_FUNC
@@ -1940,6 +1954,9 @@ avs_bits_per_component    constant 8 (8 bits/component)
   AVSC_LOAD_FUNC_OPT(avs_val_is_string);
   AVSC_LOAD_FUNC_OPT(avs_val_is_array);
   AVSC_LOAD_FUNC_OPT(avs_val_is_error);
+  // V12
+  AVSC_LOAD_FUNC_OPT(avs_acquire_global_lock);
+  AVSC_LOAD_FUNC_OPT(avs_release_global_lock);
 
 #undef __AVSC_STRINGIFY
 #undef AVSC_STRINGIFY