include/comphelper/numberedcollection.hxx

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 #ifndef INCLUDED_COMPHELPER_NUMBEREDCOLLECTION_HXX
  21 #define INCLUDED_COMPHELPER_NUMBEREDCOLLECTION_HXX
  22
  23 #include <config_options.h>
  24 #include <comphelper/comphelperdllapi.h>
  25
  26 #include <com/sun/star/uno/Reference.h>
  27 #include <com/sun/star/frame/XUntitledNumbers.hpp>
  28
  29 #include <cppuhelper/weakref.hxx>
  30 #include <cppuhelper/implbase.hxx>
  31
  32 #include <unordered_map>
  33 #include <mutex>
  34 #include <vector>
  35
  36 namespace com::sun::star::uno { class XInterface; }
  37
  38 namespace comphelper{
  39
  40 /** @short  defines a collection of UNO components, where every component will get its own unique number.
  41
  42     @descr  Such number will be unique at runtime only... but it supports fragmentation.
  43             Note: This collection uses weak references only to know her components.
  44             So lifetime of these components must be controlled outside.
  45
  46     @threadsafe
  47  */
  48 class UNLESS_MERGELIBS_MORE(COMPHELPER_DLLPUBLIC) NumberedCollection final :
  49                                               public  ::cppu::WeakImplHelper< css::frame::XUntitledNumbers >
  50 {
  51
  52     // types, const
  53     private:
  54
  55         struct TNumberedItem
  56         {
  57             css::uno::WeakReference< css::uno::XInterface > xItem;
  58             ::sal_Int32 nNumber;
  59         };
  60
  61         typedef std::unordered_map<
  62                     sal_IntPtr,
  63                     TNumberedItem  > TNumberedItemHash;
  64
  65         typedef ::std::vector< sal_IntPtr > TDeadItemList;
  66
  67
  68     // interface
  69     public:
  70
  71
  72         /** @short  lightweight constructor.
  73          */
  74         NumberedCollection();
  75
  76
  77         /** @short  free all internally used resources.
  78          */
  79         virtual ~NumberedCollection() override;
  80
  81
  82         /** set an outside component which uses this container and must be set
  83             as source of all broadcasted messages, exceptions.
  84
  85             It's holded weak only so we do not need any complex dispose sessions.
  86
  87             Note: Passing NULL as parameter will be allowed. It will reset the internal
  88             member reference only.
  89
  90             @param  xOwner
  91                     the new owner of this collection.
  92          */
  93         void setOwner (const css::uno::Reference< css::uno::XInterface >& xOwner);
  94
  95
  96         /** set the localized prefix to be used for untitled components.
  97
  98             Localization has to be done outside. This container will return
  99             those value then. There are no further checks. Its up to you to define
 100             a suitable string here :-)
 101
 102             @param  sPrefix
 103                     the new prefix for untitled components.
 104          */
 105         void setUntitledPrefix(const OUString& sPrefix);
 106
 107
 108         /** @see css.frame.XUntitledNumbers */
 109         virtual ::sal_Int32 SAL_CALL leaseNumber(const css::uno::Reference< css::uno::XInterface >& xComponent) override;
 110
 111
 112         /** @see css.frame.XUntitledNumbers */
 113         virtual void SAL_CALL releaseNumber(::sal_Int32 nNumber) override;
 114
 115
 116         /** @see css.frame.XUntitledNumbers */
 117         virtual void SAL_CALL releaseNumberForComponent(const css::uno::Reference< css::uno::XInterface >& xComponent) override;
 118
 119
 120         /** @see css.frame.XUntitledNumbers */
 121         virtual OUString SAL_CALL getUntitledPrefix() override;
 122
 123
 124     // internal
 125     private:
 126
 127
 128         /** @short  tries to find a unique number not already used within this collection.
 129
 130             @descr  It reuses the smallest number which isn't used by any component
 131                     of this collection. (fragmentation!) If collection is full (means there
 132                     is no free number) the special value INVALID_NUMBER will be returned.
 133
 134             @note   Those method can't be called within a multithreaded environment.
 135                     Because such number won't be "reserved" for the call of these method
 136                     it can happen that two calls returns the same number (reasoned by the fact that first call
 137                     doesn't used the returned number already.
 138
 139                     So the outside code has to make sure that retrieving and using of those numbers
 140                     will be an atomic operation.
 141
 142             @return a unique number or special value INVALID_NUMBER if collection is full.
 143          */
 144         ::sal_Int32 impl_searchFreeNumber ();
 145
 146         static void impl_cleanUpDeadItems (      TNumberedItemHash& lItems    ,
 147                                            const TDeadItemList&     lDeadItems);
 148
 149
 150     // member
 151     private:
 152
 153         /// localized string to be used for untitled components
 154         OUString m_sUntitledPrefix;
 155
 156         /// cache of all "leased numbers" and its bound components
 157         TNumberedItemHash m_lComponents;
 158
 159         /// used as source of broadcasted messages or exceptions (can be null !)
 160         css::uno::WeakReference< css::uno::XInterface > m_xOwner;
 161
 162         std::mutex m_aMutex;
 163 };
 164
 165 } // namespace comphelper
 166
 167 #endif // INCLUDED_COMPHELPER_NUMBEREDCOLLECTION_HXX
 168
 169 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */