X-Git-Url: https://git.lttng.org/?a=blobdiff_plain;f=include%2Flttng%2Fnotification%2Fchannel.h;h=030c88cbd3e1829ee1db2bd34fb2dc6bf43e3d4a;hb=HEAD;hp=b010df12aa56b8194241fd17af947a0c8e2e1009;hpb=53d809151fa289fc8d9391db1d878654ec713097;p=lttng-tools.git diff --git a/include/lttng/notification/channel.h b/include/lttng/notification/channel.h index b010df12a..dad62b0b3 100644 --- a/include/lttng/notification/channel.h +++ b/include/lttng/notification/channel.h @@ -1,23 +1,17 @@ /* - * Copyright (C) 2017 - Jérémie Galarneau + * Copyright (C) 2017 Jérémie Galarneau * - * This library is free software; you can redistribute it and/or modify it - * under the terms of the GNU Lesser General Public License, version 2.1 only, - * as published by the Free Software Foundation. + * SPDX-License-Identifier: LGPL-2.1-only * - * This library is distributed in the hope that it will be useful, but WITHOUT - * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or - * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License - * for more details. - * - * You should have received a copy of the GNU Lesser General Public License - * along with this library; if not, write to the Free Software Foundation, - * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA */ #ifndef LTTNG_NOTIFICATION_CHANNEL_H #define LTTNG_NOTIFICATION_CHANNEL_H +#include + +#include + #ifdef __cplusplus extern "C" { #endif @@ -29,6 +23,7 @@ struct lttng_notification_channel; enum lttng_notification_channel_status { LTTNG_NOTIFICATION_CHANNEL_STATUS_NOTIFICATIONS_DROPPED = 1, + LTTNG_NOTIFICATION_CHANNEL_STATUS_INTERRUPTED = 2, LTTNG_NOTIFICATION_CHANNEL_STATUS_OK = 0, LTTNG_NOTIFICATION_CHANNEL_STATUS_ERROR = -1, LTTNG_NOTIFICATION_CHANNEL_STATUS_CLOSED = -2, @@ -64,8 +59,8 @@ enum lttng_notification_channel_status { * The returned lttng_notification_channel must be destroyed using * the lttng_notification_channel_destroy() function. */ -extern struct lttng_notification_channel *lttng_notification_channel_create( - struct lttng_endpoint *endpoint); +LTTNG_EXPORT extern struct lttng_notification_channel * +lttng_notification_channel_create(struct lttng_endpoint *endpoint); /* * Get the next notification received on a notification channel. @@ -79,15 +74,38 @@ extern struct lttng_notification_channel *lttng_notification_channel_create( * Notifications can be dropped if a client consumes the notifications sent * through the notification channel too slowly. * - * Returns LTTNG_NOTIFICATION_CHANNEL_STATUS_OK and a notification on success, - * LTTNG_NOTIFICATION_CHANNEL_STATUS_INVALID if an invalid parameter was - * provided, or LTTNG_NOTIFICATION_CHANNEL_STATUS_NOTIFICATIONS_DROPPED if - * notifications were dropped. + * Returns + * - LTTNG_NOTIFICATION_CHANNEL_STATUS_OK and a notification on success, + * - LTTNG_NOTIFICATION_CHANNEL_STATUS_INVALID if an invalid parameter was + * provided, + * - LTTNG_NOTIFICATION_CHANNEL_STATUS_NOTIFICATIONS_DROPPED if notifications + * were dropped, + * - LTTNG_NOTIFICATION_CHANNEL_STATUS_INTERRUPTED if a signal was received + * that caused the reception to fail. + */ +LTTNG_EXPORT extern enum lttng_notification_channel_status +lttng_notification_channel_get_next_notification(struct lttng_notification_channel *channel, + struct lttng_notification **notification); + +/* + * Check whether a notification is pending on a notification channel. + * + * This call allows the user to check whether a notification is pending on + * the notification channel. + * + * If pending is set to true and the return value is + * LTTNG_NOTIFICATION_CHANNEL_STATUS_OK, + * lttng_notification_channel_get_next_notification() can be called and + * is guaranteed to not block. + * + * Returns + * - LTTNG_NOTIFICATION_CHANNEL_STATUS_OK on success, + * - LTTNG_NOTIFICATION_CHANNEL_STATUS_INVALID if an invalid parameter was + * provided. */ -extern enum lttng_notification_channel_status -lttng_notification_channel_get_next_notification( - struct lttng_notification_channel *channel, - struct lttng_notification **notification); +LTTNG_EXPORT extern enum lttng_notification_channel_status +lttng_notification_channel_has_pending_notification(struct lttng_notification_channel *channel, + bool *notification_pending); /* * Subscribe to notifications of a condition through a notification channel. @@ -98,15 +116,15 @@ lttng_notification_channel_get_next_notification( * An error will be reported if the client tries to subscribe to the same * condition multiple times without unsubscribing. * - * Returns LTTNG_NOTIFICATION_CHANNEL_STATUS_OK on success, - * LTTNG_NOTIFICATION_CHANNEL_STATUS_INVALID if an invalid parameter was - * provided, or LTTNG_NOTIFICATION_CHANNEL_STATUS_ALREADY_SUBSCRIBED if the - * client was already subscribed to the condition through this channel. + * Returns + * - LTTNG_NOTIFICATION_CHANNEL_STATUS_OK on success, + * - LTTNG_NOTIFICATION_CHANNEL_STATUS_INVALID if an invalid parameter was + * provided, or LTTNG_NOTIFICATION_CHANNEL_STATUS_ALREADY_SUBSCRIBED if the + * client was already subscribed to the condition through this channel. */ -extern enum lttng_notification_channel_status -lttng_notification_channel_subscribe( - struct lttng_notification_channel *channel, - const struct lttng_condition *condition); +LTTNG_EXPORT extern enum lttng_notification_channel_status +lttng_notification_channel_subscribe(struct lttng_notification_channel *channel, + const struct lttng_condition *condition); /* * Unsubscribe to notifications of a condition through a notification channel. @@ -117,21 +135,21 @@ lttng_notification_channel_subscribe( * An error will be reported if the client tries to unsubscribe to from a * conditions' notifications to which it was not previously subscribed. * - * Returns LTTNG_NOTIFICATION_CHANNEL_STATUS_OK on success, - * LTTNG_NOTIFICATION_CHANNEL_STATUS_INVALID if an invalid parameter was - * provided, or LTTNG_NOTIFICATION_CHANNEL_STATUS_UNKNOWN_CONDITION if the - * client was not already subscribed to the condition through this channel. + * Returns + * - LTTNG_NOTIFICATION_CHANNEL_STATUS_OK on success, + * - LTTNG_NOTIFICATION_CHANNEL_STATUS_INVALID if an invalid parameter was + * provided, or LTTNG_NOTIFICATION_CHANNEL_STATUS_UNKNOWN_CONDITION if the + * client was not already subscribed to the condition through this channel. */ -extern enum lttng_notification_channel_status -lttng_notification_channel_unsubscribe( - struct lttng_notification_channel *channel, - const struct lttng_condition *condition); +LTTNG_EXPORT extern enum lttng_notification_channel_status +lttng_notification_channel_unsubscribe(struct lttng_notification_channel *channel, + const struct lttng_condition *condition); /* * Closes and destroys (frees) a notification channel. */ -extern void lttng_notification_channel_destroy( - struct lttng_notification_channel *channel); +LTTNG_EXPORT extern void +lttng_notification_channel_destroy(struct lttng_notification_channel *channel); #ifdef __cplusplus }