1// Copyright (c) 2013 The Chromium Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5#ifndef CONTENT_BROWSER_RENDERER_HOST_MEDIA_VIDEO_CAPTURE_BUFFER_POOL_H_
6#define CONTENT_BROWSER_RENDERER_HOST_MEDIA_VIDEO_CAPTURE_BUFFER_POOL_H_
7
8#include <map>
9
10#include "base/basictypes.h"
11#include "base/memory/ref_counted.h"
12#include "base/memory/scoped_vector.h"
13#include "base/memory/shared_memory.h"
14#include "base/process/process.h"
15#include "base/synchronization/lock.h"
16#include "content/common/content_export.h"
17#include "ui/gfx/size.h"
18
19namespace media {
20
21class VideoFrame;
22
23}  // namespace media
24
25namespace content {
26
27// A thread-safe class that does the bookkeeping and lifetime management for a
28// pool of shared-memory pixel buffers cycled between an in-process producer
29// (e.g. a VideoCaptureDevice) and a set of out-of-process consumers. The pool
30// is intended to be orchestrated by a VideoCaptureController, but is designed
31// to outlive the controller if necessary.
32//
33// Producers get a buffer by calling ReserveForProducer(), and may pass on their
34// ownership to the consumer by calling HoldForConsumers(), or drop the buffer
35// (without further processing) by calling RelinquishProducerReservation().
36// Consumers signal that they are done with the buffer by calling
37// RelinquishConsumerHold().
38//
39// Buffers are allocated on demand, but there will never be more than |count|
40// buffers in existence at any time. Buffers are identified by an int value
41// called |buffer_id|. -1 (kInvalidId) is never a valid ID, and is returned by
42// some methods to indicate failure. The active set of buffer ids may change
43// over the lifetime of the buffer pool, as existing buffers are freed and
44// reallocated at larger size. When reallocation occurs, new buffer IDs will
45// circulate.
46class CONTENT_EXPORT VideoCaptureBufferPool
47    : public base::RefCountedThreadSafe<VideoCaptureBufferPool> {
48 public:
49  static const int kInvalidId;
50  explicit VideoCaptureBufferPool(int count);
51
52  // One-time (per client/per-buffer) initialization to share a particular
53  // buffer to a process. The size of the allocation is returned as
54  // |memory_size|.
55  base::SharedMemoryHandle ShareToProcess(int buffer_id,
56                                          base::ProcessHandle process_handle,
57                                          size_t* memory_size);
58
59  // Query the memory parameters of |buffer_id|. Fills in parameters in the
60  // pointer arguments, and returns true iff the buffer exists.
61  bool GetBufferInfo(int buffer_id, void** memory, size_t* size);
62
63  // Reserve or allocate a buffer of at least |size| bytes and return its id.
64  // This will fail (returning kInvalidId) if the pool already is at its |count|
65  // limit of the number of allocations, and all allocated buffers are in use by
66  // the producer and/or consumers.
67  //
68  // If successful, the reserved buffer remains reserved (and writable by the
69  // producer) until ownership is transferred either to the consumer via
70  // HoldForConsumers(), or back to the pool with
71  // RelinquishProducerReservation().
72  //
73  // On occasion, this call will decide to free an old buffer to make room for a
74  // new allocation at a larger size. If so, the ID of the destroyed buffer is
75  // returned via |buffer_id_to_drop|.
76  int ReserveForProducer(size_t size, int* buffer_id_to_drop);
77
78  // Indicate that a buffer held for the producer should be returned back to the
79  // pool without passing on to the consumer. This effectively is the opposite
80  // of ReserveForProducer().
81  void RelinquishProducerReservation(int buffer_id);
82
83  // Transfer a buffer from producer to consumer ownership.
84  // |buffer_id| must be a buffer index previously returned by
85  // ReserveForProducer(), and not already passed to HoldForConsumers().
86  void HoldForConsumers(int buffer_id, int num_clients);
87
88  // Indicate that one or more consumers are done with a particular buffer. This
89  // effectively is the opposite of HoldForConsumers(). Once the consumers are
90  // done, a buffer is returned to the pool for reuse.
91  void RelinquishConsumerHold(int buffer_id, int num_clients);
92
93  int count() const { return count_; }
94
95 private:
96  friend class base::RefCountedThreadSafe<VideoCaptureBufferPool>;
97
98  // Per-buffer state.
99  struct Buffer {
100    Buffer();
101
102    // The memory created to be shared with renderer processes.
103    base::SharedMemory shared_memory;
104
105    // Tracks whether this buffer is currently referenced by the producer.
106    bool held_by_producer;
107
108    // Number of consumer processes which hold this shared memory.
109    int consumer_hold_count;
110  };
111
112  typedef std::map<int, Buffer*> BufferMap;
113
114  virtual ~VideoCaptureBufferPool();
115
116  int ReserveForProducerInternal(size_t size, int* buffer_id_to_drop);
117
118  Buffer* GetBuffer(int buffer_id);
119
120  // The max number of buffers that the pool is allowed to have at any moment.
121  const int count_;
122
123  // Protects everything below it.
124  base::Lock lock_;
125
126  // The ID of the next buffer.
127  int next_buffer_id_;
128
129  // The buffers, indexed by |buffer_id|.
130  BufferMap buffers_;
131
132  DISALLOW_IMPLICIT_CONSTRUCTORS(VideoCaptureBufferPool);
133};
134
135}  // namespace content
136
137#endif  // CONTENT_BROWSER_RENDERER_HOST_MEDIA_VIDEO_CAPTURE_BUFFER_POOL_H_
138