changeset 6780:7a6200ad0cd3

created abstraction IDataSource
author Sebastien Jodogne <s.jodogne@gmail.com>
date Tue, 12 May 2026 20:12:12 +0200
parents d68ddc572782
children d7513954b7fb
files OrthancFramework/Resources/CMake/OrthancFrameworkConfiguration.cmake OrthancFramework/Sources/DataSource/DataSourceAnswer.cpp OrthancFramework/Sources/DataSource/DataSourceAnswer.h OrthancFramework/Sources/DataSource/DataSourceMemoryBudget.cpp OrthancFramework/Sources/DataSource/DataSourceMemoryBudget.h OrthancFramework/Sources/DataSource/DataSourceReader.cpp OrthancFramework/Sources/DataSource/DataSourceReader.h OrthancFramework/Sources/DataSource/DataSourceRequest.cpp OrthancFramework/Sources/DataSource/DataSourceRequest.h OrthancFramework/Sources/DataSource/IDataIdentifier.h OrthancFramework/Sources/DataSource/IDataSource.h
diffstat 11 files changed, 887 insertions(+), 0 deletions(-) [+]
line wrap: on
line diff
--- a/OrthancFramework/Resources/CMake/OrthancFrameworkConfiguration.cmake	Tue May 12 18:27:02 2026 +0200
+++ b/OrthancFramework/Resources/CMake/OrthancFrameworkConfiguration.cmake	Tue May 12 20:12:12 2026 +0200
@@ -656,6 +656,10 @@
   list(APPEND ORTHANC_CORE_SOURCES_INTERNAL
     ${CMAKE_CURRENT_LIST_DIR}/../../Sources/Cache/MemoryStringCache.cpp
     ${CMAKE_CURRENT_LIST_DIR}/../../Sources/Cache/SharedArchive.cpp
+    ${CMAKE_CURRENT_LIST_DIR}/../../Sources/DataSource/DataSourceAnswer.cpp
+    ${CMAKE_CURRENT_LIST_DIR}/../../Sources/DataSource/DataSourceMemoryBudget.cpp
+    ${CMAKE_CURRENT_LIST_DIR}/../../Sources/DataSource/DataSourceReader.cpp
+    ${CMAKE_CURRENT_LIST_DIR}/../../Sources/DataSource/DataSourceRequest.cpp
     ${CMAKE_CURRENT_LIST_DIR}/../../Sources/FileBuffer.cpp
     ${CMAKE_CURRENT_LIST_DIR}/../../Sources/FileStorage/FilesystemStorage.cpp
     ${CMAKE_CURRENT_LIST_DIR}/../../Sources/MetricsRegistry.cpp
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/OrthancFramework/Sources/DataSource/DataSourceAnswer.cpp	Tue May 12 20:12:12 2026 +0200
@@ -0,0 +1,182 @@
+/**
+ * Orthanc - A Lightweight, RESTful DICOM Store
+ * Copyright (C) 2012-2016 Sebastien Jodogne, Medical Physics
+ * Department, University Hospital of Liege, Belgium
+ * Copyright (C) 2017-2023 Osimis S.A., Belgium
+ * Copyright (C) 2024-2026 Orthanc Team SRL, Belgium
+ * Copyright (C) 2021-2026 Sebastien Jodogne, ICTEAM UCLouvain, Belgium
+ *
+ * This program is free software: you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * as published by the Free Software Foundation, either version 3 of
+ * the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this program. If not, see
+ * <http://www.gnu.org/licenses/>.
+ **/
+
+
+#include "../PrecompiledHeaders.h"
+#include "DataSourceAnswer.h"
+
+#include "../OrthancException.h"
+#include "DataSourceMemoryBudget.h"
+
+#include <cassert>
+
+
+namespace Orthanc
+{
+  DataSourceAnswer::Item::Item(IDataIdentifier* id /* takes ownership */,
+                               boost::shared_ptr<IDynamicObject>& value,
+                               boost::shared_ptr<Internals::DataSourceMemoryBudget>& budget,
+                               size_t memorySize) :
+    id_(id),
+    value_(value),
+    budget_(budget),
+    memorySize_(memorySize)
+  {
+    if (id == NULL ||
+        value == NULL ||
+        budget_ == NULL)
+    {
+      throw OrthancException(ErrorCode_NullPointer);
+    }
+  }
+
+
+  DataSourceAnswer::Item::Item(IDataIdentifier* id /* takes ownership */,
+                               const OrthancException& error) :
+    id_(id),
+    error_(new OrthancException(error)),
+    memorySize_(0)
+  {
+    if (id == NULL)
+    {
+      throw OrthancException(ErrorCode_NullPointer);
+    }
+  }
+
+
+  DataSourceAnswer::Item::~Item()
+  {
+    if (budget_)
+    {
+      budget_->Release(memorySize_);
+    }
+  }
+
+
+  const IDataIdentifier& DataSourceAnswer::Item::GetId() const
+  {
+    assert(id_.get() != NULL);
+    return *id_;
+  }
+
+  const boost::shared_ptr<IDynamicObject>& DataSourceAnswer::Item::GetValue() const
+  {
+    if (error_)
+    {
+      throw *error_;
+    }
+    else if (value_)
+    {
+      return value_;
+    }
+    else
+    {
+      throw OrthancException(ErrorCode_InternalError);
+    }
+  }
+
+
+  void DataSourceAnswer::EnqueueInternal(Item* item)
+  {
+    std::unique_ptr<Item> protection(item);
+
+    if (item == NULL)
+    {
+      throw OrthancException(ErrorCode_NullPointer);
+    }
+
+    {
+      boost::mutex::scoped_lock lock(mutex_);
+
+      if (countEnqueued_ >= finalSize_)
+      {
+        throw OrthancException(ErrorCode_BadSequenceOfCalls);
+      }
+      else
+      {
+        content_.push_back(protection.release());
+        countEnqueued_++;
+
+        cond_.notify_all();
+      }
+    }
+  }
+
+
+  DataSourceAnswer::DataSourceAnswer(unsigned int finalSize) :
+    countEnqueued_(0),
+    finalSize_(finalSize)
+  {
+  }
+
+
+  DataSourceAnswer::~DataSourceAnswer()
+  {
+    for (Content::iterator it = content_.begin(); it != content_.end(); ++it)
+    {
+      assert(*it != NULL);
+      delete *it;
+    }
+  }
+
+
+  DataSourceAnswer::Item* DataSourceAnswer::Dequeue()
+  {
+    boost::mutex::scoped_lock lock(mutex_);
+
+    while (countEnqueued_ < finalSize_ &&
+           content_.empty())
+    {
+      cond_.wait(lock);
+    }
+
+    assert(countEnqueued_ <= finalSize_);
+
+    if (content_.empty())
+    {
+      return NULL;
+    }
+    else
+    {
+      Item* front = content_.front();
+      content_.pop_front();
+      return front;
+    }
+  }
+
+
+  void DataSourceAnswer::EnqueueValue(IDataIdentifier* id,
+                                      boost::shared_ptr<IDynamicObject>& value,
+                                      boost::shared_ptr<Internals::DataSourceMemoryBudget>& budget,
+                                      size_t memorySize)
+  {
+    EnqueueInternal(new Item(id, value, budget, memorySize));
+  }
+
+
+  void DataSourceAnswer::EnqueueError(IDataIdentifier* id,
+                                      const OrthancException& error)
+  {
+    EnqueueInternal(new Item(id, error));
+  }
+}
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/OrthancFramework/Sources/DataSource/DataSourceAnswer.h	Tue May 12 20:12:12 2026 +0200
@@ -0,0 +1,102 @@
+/**
+ * Orthanc - A Lightweight, RESTful DICOM Store
+ * Copyright (C) 2012-2016 Sebastien Jodogne, Medical Physics
+ * Department, University Hospital of Liege, Belgium
+ * Copyright (C) 2017-2023 Osimis S.A., Belgium
+ * Copyright (C) 2024-2026 Orthanc Team SRL, Belgium
+ * Copyright (C) 2021-2026 Sebastien Jodogne, ICTEAM UCLouvain, Belgium
+ *
+ * This program is free software: you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * as published by the Free Software Foundation, either version 3 of
+ * the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this program. If not, see
+ * <http://www.gnu.org/licenses/>.
+ **/
+
+
+#pragma once
+
+#include "../Compatibility.h"
+#include "../IDynamicObject.h"
+#include "IDataIdentifier.h"
+
+#include <boost/shared_ptr.hpp>
+#include <boost/thread/condition_variable.hpp>
+#include <boost/thread/mutex.hpp>
+#include <list>
+
+
+namespace Orthanc
+{
+  class OrthancException;
+
+  namespace Internals
+  {
+    class DataSourceMemoryBudget;
+  }
+
+  class ORTHANC_PUBLIC DataSourceAnswer : public boost::noncopyable
+  {
+  public:
+    class ORTHANC_PUBLIC Item : public boost::noncopyable
+    {
+      friend class DataSourceAnswer;
+
+    private:
+      std::unique_ptr<IDataIdentifier>            id_;
+      boost::shared_ptr<IDynamicObject>           value_;
+      std::unique_ptr<OrthancException>           error_;
+      boost::shared_ptr<Internals::DataSourceMemoryBudget>  budget_;
+      size_t                                      memorySize_;
+
+      Item(IDataIdentifier* id /* takes ownership */,
+           boost::shared_ptr<IDynamicObject>& value,
+           boost::shared_ptr<Internals::DataSourceMemoryBudget>& budget,
+           size_t memorySize);
+
+      Item(IDataIdentifier* id /* takes ownership */,
+           const OrthancException& error);
+
+    public:
+      ~Item();
+
+      const IDataIdentifier& GetId() const;
+
+      const boost::shared_ptr<IDynamicObject>& GetValue() const;
+    };
+
+  private:
+    typedef std::list<Item*>  Content;
+
+    boost::mutex               mutex_;
+    boost::condition_variable  cond_;
+    Content                    content_;
+    unsigned int               countEnqueued_;
+    unsigned int               finalSize_;
+
+    void EnqueueInternal(Item* item);
+
+  public:
+    DataSourceAnswer(unsigned int finalSize);
+
+    ~DataSourceAnswer();
+
+    Item* Dequeue();
+
+    void EnqueueValue(IDataIdentifier* id,
+                      boost::shared_ptr<IDynamicObject>& value,
+                      boost::shared_ptr<Internals::DataSourceMemoryBudget>& budget,
+                      size_t memorySize);
+
+    void EnqueueError(IDataIdentifier* id,
+                      const OrthancException& error);
+  };
+}
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/OrthancFramework/Sources/DataSource/DataSourceMemoryBudget.cpp	Tue May 12 20:12:12 2026 +0200
@@ -0,0 +1,71 @@
+/**
+ * Orthanc - A Lightweight, RESTful DICOM Store
+ * Copyright (C) 2012-2016 Sebastien Jodogne, Medical Physics
+ * Department, University Hospital of Liege, Belgium
+ * Copyright (C) 2017-2023 Osimis S.A., Belgium
+ * Copyright (C) 2024-2026 Orthanc Team SRL, Belgium
+ * Copyright (C) 2021-2026 Sebastien Jodogne, ICTEAM UCLouvain, Belgium
+ *
+ * This program is free software: you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * as published by the Free Software Foundation, either version 3 of
+ * the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this program. If not, see
+ * <http://www.gnu.org/licenses/>.
+ **/
+
+
+#include "../PrecompiledHeaders.h"
+#include "DataSourceMemoryBudget.h"
+
+
+namespace Orthanc
+{
+  namespace Internals
+  {
+    DataSourceMemoryBudget::DataSourceMemoryBudget(uint64_t maximumMemory) :
+      maximumMemory_(maximumMemory),
+      currentMemory_(0)
+    {
+    }
+
+
+    void DataSourceMemoryBudget::Acquire(size_t memory) ORTHANC_NOEXCEPT
+    {
+      boost::mutex::scoped_lock lock(mutex_);
+
+      while (currentMemory_ != 0 &&  // Make sure that 1 thread can always proceed
+             currentMemory_ + memory > maximumMemory_)
+      {
+        cond_.wait(lock);
+      }
+
+      currentMemory_ += memory;
+    }
+
+
+    void DataSourceMemoryBudget::Release(size_t memory) ORTHANC_NOEXCEPT
+    {
+      boost::mutex::scoped_lock lock(mutex_);
+
+      assert(currentMemory_ >= memory);
+      currentMemory_ -= memory;
+
+      cond_.notify_all();
+    }
+
+
+    uint64_t DataSourceMemoryBudget::GetCurrentMemory() ORTHANC_NOEXCEPT
+    {
+      boost::mutex::scoped_lock lock(mutex_);
+      return currentMemory_;
+    }
+  }
+}
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/OrthancFramework/Sources/DataSource/DataSourceMemoryBudget.h	Tue May 12 20:12:12 2026 +0200
@@ -0,0 +1,58 @@
+/**
+ * Orthanc - A Lightweight, RESTful DICOM Store
+ * Copyright (C) 2012-2016 Sebastien Jodogne, Medical Physics
+ * Department, University Hospital of Liege, Belgium
+ * Copyright (C) 2017-2023 Osimis S.A., Belgium
+ * Copyright (C) 2024-2026 Orthanc Team SRL, Belgium
+ * Copyright (C) 2021-2026 Sebastien Jodogne, ICTEAM UCLouvain, Belgium
+ *
+ * This program is free software: you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * as published by the Free Software Foundation, either version 3 of
+ * the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this program. If not, see
+ * <http://www.gnu.org/licenses/>.
+ **/
+
+
+#pragma once
+
+#include "../Compatibility.h"
+
+#include <boost/noncopyable.hpp>
+#include <boost/thread/condition_variable.hpp>
+#include <boost/thread/mutex.hpp>
+#include <stdint.h>
+
+
+namespace Orthanc
+{
+  namespace Internals
+  {
+    // This is basically a semaphore with the uint64_t data type
+    class DataSourceMemoryBudget : public boost::noncopyable
+    {
+    private:
+      boost::mutex               mutex_;
+      boost::condition_variable  cond_;
+      const uint64_t             maximumMemory_;
+      uint64_t                   currentMemory_;
+
+    public:
+      DataSourceMemoryBudget(uint64_t maximumMemory);
+
+      void Acquire(size_t memory) ORTHANC_NOEXCEPT;
+
+      void Release(size_t memory) ORTHANC_NOEXCEPT;
+
+      uint64_t GetCurrentMemory() ORTHANC_NOEXCEPT;
+    };
+  }
+}
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/OrthancFramework/Sources/DataSource/DataSourceReader.cpp	Tue May 12 20:12:12 2026 +0200
@@ -0,0 +1,193 @@
+/**
+ * Orthanc - A Lightweight, RESTful DICOM Store
+ * Copyright (C) 2012-2016 Sebastien Jodogne, Medical Physics
+ * Department, University Hospital of Liege, Belgium
+ * Copyright (C) 2017-2023 Osimis S.A., Belgium
+ * Copyright (C) 2024-2026 Orthanc Team SRL, Belgium
+ * Copyright (C) 2021-2026 Sebastien Jodogne, ICTEAM UCLouvain, Belgium
+ *
+ * This program is free software: you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * as published by the Free Software Foundation, either version 3 of
+ * the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this program. If not, see
+ * <http://www.gnu.org/licenses/>.
+ **/
+
+
+#include "../PrecompiledHeaders.h"
+#include "DataSourceReader.h"
+
+#include "../Cache/SharedObjectCache.h"
+#include "../OrthancException.h"
+#include "DataSourceMemoryBudget.h"
+
+#include <boost/make_shared.hpp>
+#include <cassert>
+
+
+namespace Orthanc
+{
+  class DataSourceReader::DataSourceRunnable : public IRunnable
+  {
+  private:
+    boost::weak_ptr<DataSourceAnswer>                     answer_;
+    IDataSource&                                          source_;
+    std::unique_ptr<IDataIdentifier>                      id_;
+    boost::shared_ptr<SharedObjectCache>                  cache_;
+    boost::shared_ptr<Internals::DataSourceMemoryBudget>  budget_;
+
+  public:
+    DataSourceRunnable(boost::shared_ptr<DataSourceAnswer>& answer,
+                       IDataSource& source,
+                       IDataIdentifier* id,
+                       boost::shared_ptr<SharedObjectCache>& cache,
+                       boost::shared_ptr<Internals::DataSourceMemoryBudget>& budget) :
+      answer_(answer),
+      source_(source),
+      id_(id),
+      cache_(cache),
+      budget_(budget)
+    {
+      if (id == NULL ||
+          answer.get() == NULL)
+      {
+        throw OrthancException(ErrorCode_NullPointer);
+      }
+    }
+
+    virtual void Run() ORTHANC_OVERRIDE
+    {
+      // Phase 1: Do all the work WITHOUT holding a strong reference to "DataSourceAnswer".
+      boost::shared_ptr<IDynamicObject> value;
+      std::unique_ptr<OrthancException> error;
+
+      if (cache_)
+      {
+        value = cache_->GetCachedValue(id_->GetCacheKey());
+      }
+
+      if (!value)
+      {
+        try
+        {
+          value.reset(source_.Load(*id_));
+        }
+        catch (OrthancException& e)
+        {
+          error.reset(new OrthancException(e));
+        }
+        catch (...)
+        {
+          error.reset(new OrthancException(ErrorCode_InternalError));
+        }
+
+        if (!error && !value)
+        {
+          error.reset(new OrthancException(ErrorCode_NullPointer));
+        }
+
+        if (!error && cache_)
+        {
+          cache_->Store(id_->GetCacheKey(), value);
+        }
+      }
+
+      // Phase 2: Acquire budget WITHOUT holding a strong reference to "DataSourceAnswer".
+      // If the "DataSourceAnswer" has been dropped, "answer_.lock()" below will return NULL
+      // and we will immediately "Release()" to revert this.
+      size_t size = 0;
+
+      if (!error)
+      {
+        size = source_.GetSize(*value);
+        budget_->Acquire(size);   // may block; "DataSourceAnswer" CAN be destroyed here
+      }
+
+      // Phase 3: Only now take a strong reference to "DataSourceAnswer".
+      {
+        boost::shared_ptr<DataSourceAnswer> lock = answer_.lock();
+
+        if (!lock)
+        {
+          // Answer was abandoned while we were blocked in Acquire().
+          // Undo the charge and exit cleanly.
+          if (!error)
+          {
+            budget_->Release(size);
+          }
+        }
+        else
+        {
+          if (error)
+          {
+            lock->EnqueueError(id_.release(), *error);
+          }
+          else
+          {
+            lock->EnqueueValue(id_.release(), value, budget_, size);
+          }
+        }
+      }
+    }
+  };
+
+
+  DataSourceReader::DataSourceReader(IExecutorService* executor /* takes ownership */,
+                                     IDataSource* source /* takes ownership */) :
+    executor_(executor),
+    source_(source),
+    budget_(new Internals::DataSourceMemoryBudget(0))
+  {
+    if (executor == NULL ||
+        source == NULL)
+    {
+      throw OrthancException(ErrorCode_NullPointer);
+    }
+  }
+
+
+  DataSourceReader::~DataSourceReader()
+  {
+    executor_.reset();
+    source_.reset();
+
+    assert(budget_->GetCurrentMemory() == 0);
+  }
+
+
+  void DataSourceReader::CreateCache(IObjectSizeProvider* provider /* takes ownership */,
+                                     size_t capacity)
+  {
+    cache_ = boost::make_shared<SharedObjectCache>(provider, capacity);
+  }
+
+
+  void DataSourceReader::SetMaximumMemory(uint64_t maximumMemory)
+  {
+    budget_ = boost::make_shared<Internals::DataSourceMemoryBudget>(maximumMemory);
+  }
+
+
+  boost::shared_ptr<DataSourceAnswer> DataSourceReader::Submit(DataSourceRequest* request /* takes ownership */)
+  {
+    std::unique_ptr<DataSourceRequest> protection(request);
+
+    boost::shared_ptr<DataSourceAnswer> answer(new DataSourceAnswer(protection->GetSize()));
+
+    while (!protection->IsEmpty())
+    {
+      std::unique_ptr<IDataIdentifier> identifier(protection->Dequeue());
+      executor_->Submit(new DataSourceRunnable(answer, *source_, identifier.release(), cache_, budget_));
+    }
+
+    return answer;
+  }
+}
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/OrthancFramework/Sources/DataSource/DataSourceReader.h	Tue May 12 20:12:12 2026 +0200
@@ -0,0 +1,70 @@
+/**
+ * Orthanc - A Lightweight, RESTful DICOM Store
+ * Copyright (C) 2012-2016 Sebastien Jodogne, Medical Physics
+ * Department, University Hospital of Liege, Belgium
+ * Copyright (C) 2017-2023 Osimis S.A., Belgium
+ * Copyright (C) 2024-2026 Orthanc Team SRL, Belgium
+ * Copyright (C) 2021-2026 Sebastien Jodogne, ICTEAM UCLouvain, Belgium
+ *
+ * This program is free software: you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * as published by the Free Software Foundation, either version 3 of
+ * the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this program. If not, see
+ * <http://www.gnu.org/licenses/>.
+ **/
+
+
+#pragma once
+
+#include "../MultiThreading/IExecutorService.h"
+#include "DataSourceAnswer.h"
+#include "DataSourceRequest.h"
+#include "IDataSource.h"
+
+
+namespace Orthanc
+{
+  class SharedObjectCache;
+
+  namespace Internals
+  {
+    class DataSourceMemoryBudget;
+  }
+
+  class ORTHANC_PUBLIC DataSourceReader : public boost::noncopyable
+  {
+  private:
+    class DataSourceRunnable;
+
+    std::unique_ptr<IExecutorService>                     executor_;
+    std::unique_ptr<IDataSource>                          source_;
+    boost::shared_ptr<SharedObjectCache>                  cache_;
+    boost::shared_ptr<Internals::DataSourceMemoryBudget>  budget_;
+
+  public:
+    DataSourceReader(IExecutorService* executor /* takes ownership */,
+                     IDataSource* source /* takes ownership */);
+
+    ~DataSourceReader();
+
+    void CreateCache(IObjectSizeProvider* provider /* takes ownership */,
+                     size_t capacity);
+
+    void SetMaximumMemory(uint64_t maximumMemory);
+
+    boost::shared_ptr<DataSourceAnswer> Submit(DataSourceRequest* request /* takes ownership */);
+
+    void Stop()
+    {
+      executor_->Stop();
+    }
+  };
+}
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/OrthancFramework/Sources/DataSource/DataSourceRequest.cpp	Tue May 12 20:12:12 2026 +0200
@@ -0,0 +1,69 @@
+/**
+ * Orthanc - A Lightweight, RESTful DICOM Store
+ * Copyright (C) 2012-2016 Sebastien Jodogne, Medical Physics
+ * Department, University Hospital of Liege, Belgium
+ * Copyright (C) 2017-2023 Osimis S.A., Belgium
+ * Copyright (C) 2024-2026 Orthanc Team SRL, Belgium
+ * Copyright (C) 2021-2026 Sebastien Jodogne, ICTEAM UCLouvain, Belgium
+ *
+ * This program is free software: you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * as published by the Free Software Foundation, either version 3 of
+ * the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this program. If not, see
+ * <http://www.gnu.org/licenses/>.
+ **/
+
+
+#include "../PrecompiledHeaders.h"
+#include "DataSourceRequest.h"
+
+#include "../OrthancException.h"
+
+#include <cassert>
+
+
+namespace Orthanc
+{
+  DataSourceRequest::~DataSourceRequest()
+  {
+    for (Content::iterator it = content_.begin(); it != content_.end(); ++it)
+    {
+      assert(*it != NULL);
+      delete *it;
+    }
+  }
+
+
+  void DataSourceRequest::Enqueue(IDataIdentifier* id)
+  {
+    if (id == NULL)
+    {
+      throw OrthancException(ErrorCode_NullPointer);
+    }
+
+    content_.push_back(id);
+  }
+
+
+  IDataIdentifier* DataSourceRequest::Dequeue()
+  {
+    if (content_.empty())
+    {
+      throw OrthancException(ErrorCode_BadSequenceOfCalls);
+    }
+    else
+    {
+      IDataIdentifier* front = content_.front();
+      content_.pop_front();
+      return front;
+    }
+  }
+}
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/OrthancFramework/Sources/DataSource/DataSourceRequest.h	Tue May 12 20:12:12 2026 +0200
@@ -0,0 +1,58 @@
+/**
+ * Orthanc - A Lightweight, RESTful DICOM Store
+ * Copyright (C) 2012-2016 Sebastien Jodogne, Medical Physics
+ * Department, University Hospital of Liege, Belgium
+ * Copyright (C) 2017-2023 Osimis S.A., Belgium
+ * Copyright (C) 2024-2026 Orthanc Team SRL, Belgium
+ * Copyright (C) 2021-2026 Sebastien Jodogne, ICTEAM UCLouvain, Belgium
+ *
+ * This program is free software: you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * as published by the Free Software Foundation, either version 3 of
+ * the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this program. If not, see
+ * <http://www.gnu.org/licenses/>.
+ **/
+
+
+#pragma once
+
+#include "IDataIdentifier.h"
+
+#include <list>
+
+
+namespace Orthanc
+{
+  class ORTHANC_PUBLIC DataSourceRequest : public boost::noncopyable
+  {
+  private:
+    typedef std::list<IDataIdentifier*>  Content;
+
+    Content  content_;
+
+  public:
+    ~DataSourceRequest();
+
+    void Enqueue(IDataIdentifier* id);
+
+    IDataIdentifier* Dequeue();
+
+    bool IsEmpty() const
+    {
+      return content_.empty();
+    }
+
+    size_t GetSize() const
+    {
+      return content_.size();
+    }
+  };
+}
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/OrthancFramework/Sources/DataSource/IDataIdentifier.h	Tue May 12 20:12:12 2026 +0200
@@ -0,0 +1,43 @@
+/**
+ * Orthanc - A Lightweight, RESTful DICOM Store
+ * Copyright (C) 2012-2016 Sebastien Jodogne, Medical Physics
+ * Department, University Hospital of Liege, Belgium
+ * Copyright (C) 2017-2023 Osimis S.A., Belgium
+ * Copyright (C) 2024-2026 Orthanc Team SRL, Belgium
+ * Copyright (C) 2021-2026 Sebastien Jodogne, ICTEAM UCLouvain, Belgium
+ *
+ * This program is free software: you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * as published by the Free Software Foundation, either version 3 of
+ * the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this program. If not, see
+ * <http://www.gnu.org/licenses/>.
+ **/
+
+
+#pragma once
+
+#include "../OrthancFramework.h"
+
+#include <boost/noncopyable.hpp>
+
+
+namespace Orthanc
+{
+  class ORTHANC_PUBLIC IDataIdentifier : public boost::noncopyable
+  {
+  public:
+    virtual ~IDataIdentifier()
+    {
+    }
+
+    virtual std::string GetCacheKey() const = 0;
+  };
+}
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/OrthancFramework/Sources/DataSource/IDataSource.h	Tue May 12 20:12:12 2026 +0200
@@ -0,0 +1,37 @@
+/**
+ * Orthanc - A Lightweight, RESTful DICOM Store
+ * Copyright (C) 2012-2016 Sebastien Jodogne, Medical Physics
+ * Department, University Hospital of Liege, Belgium
+ * Copyright (C) 2017-2023 Osimis S.A., Belgium
+ * Copyright (C) 2024-2026 Orthanc Team SRL, Belgium
+ * Copyright (C) 2021-2026 Sebastien Jodogne, ICTEAM UCLouvain, Belgium
+ *
+ * This program is free software: you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * as published by the Free Software Foundation, either version 3 of
+ * the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this program. If not, see
+ * <http://www.gnu.org/licenses/>.
+ **/
+
+
+#pragma once
+
+#include "../Cache/IObjectSizeProvider.h"
+#include "IDataIdentifier.h"
+
+namespace Orthanc
+{
+  class ORTHANC_PUBLIC IDataSource : public IObjectSizeProvider
+  {
+  public:
+    virtual IDynamicObject* Load(const IDataIdentifier& identifier) = 0;
+  };
+}