Add documentation for semaphore and add a semaphore_try_wait function.

/******************************************************************************

 *

 *  Copyright (C) 2014 Google, Inc.

 *

 *  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.

 *

 ******************************************************************************/

#pragma once

#include <stdbool.h>

struct semaphore_t;

typedef struct semaphore_t semaphore_t;

// Creates a new semaphore with an initial value of |value|.

// Returns NULL on failure. The returned object must be released

// with |semaphore_free|.

semaphore_t *semaphore_new(unsigned int value);

// Frees a semaphore allocated with |semaphore_new|. |semaphore| may

// be NULL.

void semaphore_free(semaphore_t *semaphore);

// Decrements the value of |semaphore|. If it is 0, this call blocks until

// it becomes non-zero. |semaphore| may not be NULL.

void semaphore_wait(semaphore_t *semaphore);

// Tries to decrement the value of |semaphore|. Returns true if the value was

// decremented, false if the value was 0. This function never blocks. |semaphore|

// may not be NULL.

bool semaphore_try_wait(semaphore_t *semaphore);

// Increments the value of |semaphore|. |semaphore| may not be NULL.

void semaphore_post(semaphore_t *semaphore);

/******************************************************************************

 *

 *  Copyright (C) 2014 Google, Inc.

 *

 *  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.

 *

 ******************************************************************************/

#define LOG_TAG "osi_semaphore"

#include <assert.h>

#include <errno.h>

#include <fcntl.h>

#include <string.h>

#include <sys/eventfd.h>

#include <utils/Log.h>

    ALOGE("%s unable to wait on semaphore: %s", __func__, strerror(errno));

}

bool semaphore_try_wait(semaphore_t *semaphore) {

  assert(semaphore != NULL);

  assert(semaphore->fd != -1);

  int flags = fcntl(semaphore->fd, F_GETFL);

  if (flags == -1) {

    ALOGE("%s unable to get flags for semaphore fd: %s", __func__, strerror(errno));

    return false;

  }

  if (fcntl(semaphore->fd, F_SETFL, flags | O_NONBLOCK) == -1) {

    ALOGE("%s unable to set O_NONBLOCK for semaphore fd: %s", __func__, strerror(errno));

    return false;

  }

  eventfd_t value;

  if (eventfd_read(semaphore->fd, &value) == -1)

    return false;

  if (fcntl(semaphore->fd, F_SETFL, flags) == -1)

    ALOGE("%s unable to resetore flags for semaphore fd: %s", __func__, strerror(errno));

  return true;

}

void semaphore_post(semaphore_t *semaphore) {

  assert(semaphore != NULL);

  assert(semaphore->fd != -1);