/*
 * %CopyrightBegin%
 *
 * Copyright Ericsson AB 2006-2018. All Rights Reserved.
 *
 * 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.
 *
 * %CopyrightEnd%
 */
/**
 * @description: Poll interface functions
 * @author Lukas Larsson
 *
 * The functions in the header are used to interact with the poll
 * implementation. Iff the kernel-poll implementation needs a fallback
 * pollset, then all functions are exported twice. Once with a _flbk
 * suffix and once without any suffix. If no fallback is needed, then
 * only the non-suffix version is exported.
 */

/**
 * Initialize the poll implementation. Has to be called before any other function.
 * @param[out] concurrent_waiters if not NULL, set to 1 if more then one thread
 * is allowed to wait in the pollsets at the same time.
 */
void ERTS_POLL_EXPORT(erts_poll_init)(int *concurrent_waiters);
/**
 * @brief Create a new pollset.
 * @param id The unique debug id of this pollset.
 */
ErtsPollSet *ERTS_POLL_EXPORT(erts_poll_create_pollset)(int id);

/**
 * Modify the contents of a pollset. This function can be called while one
 * (or possibly more) thread is waiting in the pollset.
 *
 * @param ps the pollset to modify
 * @param fd the file descriptor to modify
 * @param op the type of operation to do. Normal usage is ADD,MOD...MOD,DEL.
 * @param evts the events that we are changing interest to. Ignored if op is DEL.
 * @param[in] wake_poller if set to 1 any thread waiting in the pollset will be woken.
 *   This parameter is ignored if the pollset supports concurrent waiters.
 * @param[out] wake_poller set to 1 if the waiting thread was woken.
 * @return The events set, or ERTS_POLL_EV_NVAL if it was not possible to add the
 * fd to the pollset.
 */
ErtsPollEvents ERTS_POLL_EXPORT(erts_poll_control)(ErtsPollSet *ps,
                                                   ErtsSysFdType fd,
                                                   ErtsPollOp op,
                                                   ErtsPollEvents evts,
                                                   int *wake_poller);

/**
 * Wait for events to be ready in the pollset. If the erts_poll_init call
 * set concurrent_waiters to 1, then multiple threads are allowed to call
 * this function at the same time.
 *
 * When an event has been triggered on a fd, that event is disabled. To
 * re-enable it the implementation has to call erts_poll_control again.
 *
 * @param ps the pollset to wait for events in
 * @param res an array of fd results that the ready fds are put in.
 * @param[in] length the length of the res array
 * @param[out] length the number of ready events returned in res
 * @param tpd the thread progress data to note sleep state in
 * @param timeout_time the time in native to wake up at
 * @return 0 on success, else the ERRNO of the error that happened.
 */
int ERTS_POLL_EXPORT(erts_poll_wait)(ErtsPollSet *ps,
                                     ErtsPollResFd res[],
                                     int *length,
                                     ErtsThrPrgrData *tpd,
                                     ErtsMonotonicTime timeout_time);
/**
 * Interrupt the thread waiting in the pollset. This function should be called
 * with set = 0 before any thread calls erts_poll_wait in order to clear any
 * interrupts that have happened while the thread was awake.
 *
 * This function has no effect on pollsets that support concurrent waiters.
 *
 * @param ps the pollset to wake
 * @param set if 1, interrupt the pollset, if 0 clear the interrupt flag.
 */
void ERTS_POLL_EXPORT(erts_poll_interrupt)(ErtsPollSet *ps, int set);

/* Debug functions */

/**
 * Get the maximum number of fds supported by the pollset
 */
int ERTS_POLL_EXPORT(erts_poll_max_fds)(void);
/**
 * Get information about the given pollset
 */
void ERTS_POLL_EXPORT(erts_poll_info)(ErtsPollSet *ps,
                                      ErtsPollInfo *info);
/**
 * Get information about which events are currently selected.
 *
 * The unix fd is used to index into the array, so naturally this function does
 * not work on windows. If the pollset cannot figure out what the selected
 * events for a given fd is, it is set to ERTS_POLL_EV_NONE.
 *
 * @param ps the pollset to get events from
 * @param evts an array of which events are selected on.
 */
void ERTS_POLL_EXPORT(erts_poll_get_selected_events)(ErtsPollSet *ps,
                                                     ErtsPollEvents evts[],
                                                     int length);

#ifdef ERTS_ENABLE_LOCK_COUNT
/**
 * Enable lock counting of any locks within the pollset.
 */
void ERTS_POLL_EXPORT(erts_lcnt_enable_pollset_lock_count)(ErtsPollSet *, int enable);
#endif