include/ui/Fence.h

   1 /*
   2  * Copyright (C) 2012 The Android Open Source Project
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef ANDROID_FENCE_H
  18 #define ANDROID_FENCE_H
  19
  20 #include <stdint.h>
  21 #include <sys/types.h>
  22
  23 #include <ui/ANativeObjectBase.h>
  24 #include <ui/PixelFormat.h>
  25 #include <ui/Rect.h>
  26 #include <utils/Flattenable.h>
  27 #include <utils/String8.h>
  28 #include <utils/Timers.h>
  29
  30 struct ANativeWindowBuffer;
  31
  32 namespace android {
  33
  34 // ===========================================================================
  35 // Fence
  36 // ===========================================================================
  37
  38 class Fence
  39     : public LightRefBase<Fence>, public Flattenable
  40 {
  41 public:
  42     static const sp<Fence> NO_FENCE;
  43
  44     // TIMEOUT_NEVER may be passed to the wait method to indicate that it
  45     // should wait indefinitely for the fence to signal.
  46     enum { TIMEOUT_NEVER = -1 };
  47
  48     // Construct a new Fence object with an invalid file descriptor.  This
  49     // should be done when the Fence object will be set up by unflattening
  50     // serialized data.
  51     Fence();
  52
  53     // Construct a new Fence object to manage a given fence file descriptor.
  54     // When the new Fence object is destructed the file descriptor will be
  55     // closed.
  56     Fence(int fenceFd);
  57
  58     // Check whether the Fence has an open fence file descriptor. Most Fence
  59     // methods treat an invalid file descriptor just like a valid fence that
  60     // is already signalled, so using this is usually not necessary.
  61     bool isValid() const { return mFenceFd != -1; }
  62
  63     // wait waits for up to timeout milliseconds for the fence to signal.  If
  64     // the fence signals then NO_ERROR is returned. If the timeout expires
  65     // before the fence signals then -ETIME is returned.  A timeout of
  66     // TIMEOUT_NEVER may be used to indicate that the call should wait
  67     // indefinitely for the fence to signal.
  68     status_t wait(unsigned int timeout);
  69
  70     // waitForever is a convenience function for waiting forever for a fence to
  71     // signal (just like wait(TIMEOUT_NEVER)), but issuing an error to the
  72     // system log and fence state to the kernel log if the wait lasts longer
  73     // than a warning timeout.
  74     // The logname argument should be a string identifying
  75     // the caller and will be included in the log message.
  76     status_t waitForever(const char* logname);
  77
  78     // merge combines two Fence objects, creating a new Fence object that
  79     // becomes signaled when both f1 and f2 are signaled (even if f1 or f2 is
  80     // destroyed before it becomes signaled).  The name argument specifies the
  81     // human-readable name to associated with the new Fence object.
  82     static sp<Fence> merge(const String8& name, const sp<Fence>& f1,
  83             const sp<Fence>& f2);
  84
  85     // Return a duplicate of the fence file descriptor. The caller is
  86     // responsible for closing the returned file descriptor. On error, -1 will
  87     // be returned and errno will indicate the problem.
  88     int dup() const;
  89
  90     // getSignalTime returns the system monotonic clock time at which the
  91     // fence transitioned to the signaled state.  If the fence is not signaled
  92     // then INT64_MAX is returned.  If the fence is invalid or if an error
  93     // occurs then -1 is returned.
  94     nsecs_t getSignalTime() const;
  95
  96     // Flattenable interface
  97     size_t getFlattenedSize() const;
  98     size_t getFdCount() const;
  99     status_t flatten(void* buffer, size_t size,
 100             int fds[], size_t count) const;
 101     status_t unflatten(void const* buffer, size_t size,
 102             int fds[], size_t count);
 103
 104 private:
 105     // Only allow instantiation using ref counting.
 106     friend class LightRefBase<Fence>;
 107     virtual ~Fence();
 108
 109     // Disallow copying
 110     Fence(const Fence& rhs);
 111     Fence& operator = (const Fence& rhs);
 112     const Fence& operator = (const Fence& rhs) const;
 113
 114     int mFenceFd;
 115 };
 116
 117 }; // namespace android
 118
 119 #endif // ANDROID_FENCE_H