include/fmq/EventFlag.h

/*
 * Copyright (C) 2016 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#ifndef HIDL_EVENTFLAG_H
#define HIDL_EVENTFLAG_H

#include <time.h>
#include <utils/Errors.h>
#include <atomic>

namespace android {
namespace hardware {

/**
 * EventFlag is an abstraction that application code utilizing FMQ can use to wait on
 * conditions like full, empty, data available etc. The same EventFlag object
 * can be used with multiple FMQs.
 */
struct EventFlag {
    /**
     * Create an event flag object with mapping information.
     *
     * @param fd File descriptor to be mmapped to create the event flag word.
     * There is no transfer of ownership of the fd. The caller will still
     * own the fd for the purpose of closing it.
     * @param offset Offset parameter to mmap.
     * @param ef Pointer to address of the EventFlag object that gets created. Will be set to
     * nullptr if unsuccesful.
     *
     * @return status Returns a status_t error code. Likely error codes are
     * NO_ERROR if the method is successful or BAD_VALUE due to invalid
     * mapping arguments.
     */
    static status_t createEventFlag(int fd, off_t offset, EventFlag** ef);

    /**
     * Create an event flag object from the address of the flag word.
     *
     * @param  efWordPtr Pointer to the event flag word.
     * @param status Returns a status_t error code. Likely error codes are
     * NO_ERROR if the method is successful or BAD_VALUE if efWordPtr is a null
     * pointer.
     * @param ef Pointer to the address of the EventFlag object that gets created. Will be set to
     * nullptr if unsuccesful.
     *
     * @return Returns a status_t error code. Likely error codes are
     * NO_ERROR if the method is successful or BAD_VALUE if efAddr is a null
     * pointer.
     *
     */
    static status_t createEventFlag(std::atomic<uint32_t>* efWordPtr,
                                    EventFlag** ef);

    /**
     * Delete an EventFlag object.
     *
     * @param ef A double pointer to the EventFlag object to be destroyed.
     *
     * @return Returns a status_t error code. Likely error codes are
     * NO_ERROR if the method is successful or BAD_VALUE due to
     * a bad input parameter.
     */
    static status_t deleteEventFlag(EventFlag** ef);

    /**
     * Set the specified bits of the event flag word here and wake up a thread.
     * @param bitmask The bits to be set on the event flag word.
     *
     * @return Returns a status_t error code. Likely error codes are
     * NO_ERROR if the method is successful or BAD_VALUE if the bit mask
     * does not have any bits set.
     */
    status_t wake(uint32_t bitmask);

    /**
     * Wait for any of the bits in the bit mask to be set.
     *
     * @param bitmask The bits to wait on.
     * @param timeoutNanoSeconds Specifies timeout duration in nanoseconds. It is converted to
     * an absolute timeout for the wait according to the CLOCK_MONOTONIC clock.
     * @param efState The event flag bits that caused the return from wake.
     * @param retry If true, retry automatically for a spurious wake. If false,
     * will return -EINTR or -EAGAIN for a spurious wake.
     *
     * @return Returns a status_t error code. Likely error codes are
     * NO_ERROR if the method is successful, BAD_VALUE due to bad input
     * parameters, TIMED_OUT if the wait timedout as per the timeout
     * parameter, -EAGAIN or -EINTR to indicate that the caller needs to invoke
     * wait() again. -EAGAIN or -EINTR error codes will not be returned if
     * 'retry' is true since the method will retry waiting in that case.
     */
    status_t wait(uint32_t bitmask,
                  uint32_t* efState,
                  int64_t timeOutNanoSeconds = 0,
                  bool retry = false);
private:
    bool mEfWordNeedsUnmapping = false;
    std::atomic<uint32_t>* mEfWordPtr = nullptr;

    /*
     * mmap memory for the event flag word.
     */
    EventFlag(int fd, off_t offset, status_t* status);

    /*
     * Use this constructor if we already know where the event flag word
     * lives.
     */
    EventFlag(std::atomic<uint32_t>* efWordPtr, status_t* status);

    /*
     * Disallow constructor without argument and copying.
     */
    EventFlag();
    EventFlag& operator=(const EventFlag& other) = delete;
    EventFlag(const EventFlag& other) = delete;

    /*
     * Wait for any of the bits in the bit mask to be set.
     */
    status_t waitHelper(uint32_t bitmask, uint32_t* efState, int64_t timeOutNanoSeconds);

    /*
     * Utility method to unmap the event flag word.
     */
    static status_t unmapEventFlagWord(std::atomic<uint32_t>* efWordPtr,
                                       bool* efWordNeedsUnmapping);

    /*
     * Utility method to convert timeout duration to an absolute CLOCK_MONOTONIC
     * clock time which is required by futex syscalls.
     */
    inline void addNanosecondsToCurrentTime(int64_t nanoseconds, struct timespec* timeAbs);
    ~EventFlag();
};
}  // namespace hardware
}  // namespace android
#endif