src/bthread/id.h - brpc - Git at Google

 // Licensed to the Apache Software Foundation (ASF) under one
 // or more contributor license agreements.  See the NOTICE file
 // distributed with this work for additional information
 // regarding copyright ownership.  The ASF licenses this file
 // to you 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.

 // bthread - An M:N threading library to make applications more concurrent.

 // Date: Tue Jul 10 17:40:58 CST 2012

 #ifndef BTHREAD_ID_H
 #define BTHREAD_ID_H

 #include "butil/macros.h"              // BAIDU_SYMBOLSTR
 #include "bthread/types.h"

 __BEGIN_DECLS

 // ----------------------------------------------------------------------
 // Functions to create 64-bit identifiers that can be attached with data
 // and locked without ABA issues. All functions can be called from
 // multiple threads simultaneously. Notice that bthread_id_t is designed
 // for managing a series of non-heavily-contended actions on an object.
 // It's slower than mutex and not proper for general synchronizations.
 // ----------------------------------------------------------------------

 // Create a bthread_id_t and put it into *id. Crash when `id' is NULL.
 // id->value will never be zero.
 // `on_error' will be called after bthread_id_error() is called.
 // -------------------------------------------------------------------------
 // ! User must call bthread_id_unlock() or bthread_id_unlock_and_destroy()
 // ! inside on_error.
 // -------------------------------------------------------------------------
 // Returns 0 on success, error code otherwise.
 int bthread_id_create(
     bthread_id_t* id, void* data,
     int (*on_error)(bthread_id_t id, void* data, int error_code));

 // When this function is called successfully, *id, *id+1 ... *id + range - 1
 // are mapped to same internal entity. Operations on any of the id work as
 // if they're manipulating a same id. `on_error' is called with the id issued
 // by corresponding bthread_id_error(). This is designed to let users encode
 // versions into identifiers.
 // `range' is limited inside [1, 1024].
 int bthread_id_create_ranged(
     bthread_id_t* id, void* data,
     int (*on_error)(bthread_id_t id, void* data, int error_code),
     int range);

 // Wait until `id' being destroyed.
 // Waiting on a destroyed bthread_id_t returns immediately.
 // Returns 0 on success, error code otherwise.
 int bthread_id_join(bthread_id_t id);

 // Destroy a created but never-used bthread_id_t.
 // Returns 0 on success, EINVAL otherwise.
 int bthread_id_cancel(bthread_id_t id);

 // Issue an error to `id'.
 // If `id' is not locked, lock the id and run `on_error' immediately. Otherwise
 // `on_error' will be called with the error just before `id' being unlocked.
 // If `id' is destroyed, un-called on_error are dropped.
 // Returns 0 on success, error code otherwise.
 #define bthread_id_error(id, err)                                        \
     bthread_id_error_verbose(id, err, __FILE__ ":" BAIDU_SYMBOLSTR(__LINE__))

 int bthread_id_error_verbose(bthread_id_t id, int error_code,
                              const char *location);

 // Make other bthread_id_lock/bthread_id_trylock on the id fail, the id must
 // already be locked. If the id is unlocked later rather than being destroyed,
 // effect of this function is cancelled. This function avoids useless
 // waiting on a bthread_id which will be destroyed soon but still needs to
 // be joinable.
 // Returns 0 on success, error code otherwise.
 int bthread_id_about_to_destroy(bthread_id_t id);

 // Try to lock `id' (for using the data exclusively)
 // On success return 0 and set `pdata' with the `data' parameter to
 // bthread_id_create[_ranged], EBUSY on already locked, error code otherwise.
 int bthread_id_trylock(bthread_id_t id, void** pdata);

 // Lock `id' (for using the data exclusively). If `id' is locked
 // by others, wait until `id' is unlocked or destroyed.
 // On success return 0 and set `pdata' with the `data' parameter to
 // bthread_id_create[_ranged], error code otherwise.
 #define bthread_id_lock(id, pdata)                                      \
     bthread_id_lock_verbose(id, pdata, __FILE__ ":" BAIDU_SYMBOLSTR(__LINE__))
 int bthread_id_lock_verbose(bthread_id_t id, void** pdata,
                             const char *location);

 // Lock `id' (for using the data exclusively) and reset the range. If `id' is
 // locked by others, wait until `id' is unlocked or destroyed. if `range' is
 // smaller than the original range of this id, nothing happens about the range
 #define bthread_id_lock_and_reset_range(id, pdata, range)               \
     bthread_id_lock_and_reset_range_verbose(id, pdata, range,           \
                                __FILE__ ":" BAIDU_SYMBOLSTR(__LINE__))
 int bthread_id_lock_and_reset_range_verbose(
     bthread_id_t id, void **pdata,
     int range, const char *location);

 // Unlock `id'. Must be called after a successful call to bthread_id_trylock()
 // or bthread_id_lock().
 // Returns 0 on success, error code otherwise.
 int bthread_id_unlock(bthread_id_t id);

 // Unlock and destroy `id'. Waiters blocking on bthread_id_join() or
 // bthread_id_lock() will wake up. Must be called after a successful call to
 // bthread_id_trylock() or bthread_id_lock().
 // Returns 0 on success, error code otherwise.
 int bthread_id_unlock_and_destroy(bthread_id_t id);

 // **************************************************************************
 // bthread_id_list_xxx functions are NOT thread-safe unless explicitly stated

 // Initialize a list for storing bthread_id_t. When an id is destroyed, it will
 // be removed from the list automatically.
 // The commented parameters are not used anymore and just kept to not break
 // compatibility.
 int bthread_id_list_init(bthread_id_list_t* list,
                          unsigned /*size*/,
                          unsigned /*conflict_size*/);
 // Destroy the list.
 void bthread_id_list_destroy(bthread_id_list_t* list);

 // Add a bthread_id_t into the list.
 int bthread_id_list_add(bthread_id_list_t* list, bthread_id_t id);

 // Swap internal fields of two lists.
 void bthread_id_list_swap(bthread_id_list_t* dest,
                           bthread_id_list_t* src);

 // Issue error_code to all bthread_id_t inside `list' and clear `list'.
 // Notice that this function iterates all id inside the list and may call
 // on_error() of each valid id in-place, in another word, this thread-unsafe
 // function is not suitable to be enclosed within a lock directly.
 // To make the critical section small, swap the list inside the lock and
 // reset the swapped list outside the lock as follows:
 //   bthread_id_list_t tmplist;
 //   bthread_id_list_init(&tmplist, 0, 0);
 //   LOCK;
 //   bthread_id_list_swap(&tmplist, &the_list_to_reset);
 //   UNLOCK;
 //   bthread_id_list_reset(&tmplist, error_code);
 //   bthread_id_list_destroy(&tmplist);
 int bthread_id_list_reset(bthread_id_list_t* list, int error_code);
 // Following 2 functions wrap above process.
 int bthread_id_list_reset_pthreadsafe(
     bthread_id_list_t* list, int error_code, pthread_mutex_t* mutex);
 int bthread_id_list_reset_bthreadsafe(
     bthread_id_list_t* list, int error_code, bthread_mutex_t* mutex);

 __END_DECLS

 #if defined(__cplusplus)
 // cpp specific API, with an extra `error_text' so that error information
 // is more comprehensive
 int bthread_id_create2(
     bthread_id_t* id, void* data,
     int (*on_error)(bthread_id_t id, void* data, int error_code,
                     const std::string& error_text));
 int bthread_id_create2_ranged(
     bthread_id_t* id, void* data,
     int (*on_error)(bthread_id_t id, void* data, int error_code,
                     const std::string& error_text),
     int range);
 #define bthread_id_error2(id, ec, et)                                   \
     bthread_id_error2_verbose(id, ec, et, __FILE__ ":" BAIDU_SYMBOLSTR(__LINE__))
 int bthread_id_error2_verbose(bthread_id_t id, int error_code,
                               const std::string& error_text,
                               const char *location);
 int bthread_id_list_reset2(bthread_id_list_t* list, int error_code,
                            const std::string& error_text);
 int bthread_id_list_reset2_pthreadsafe(bthread_id_list_t* list, int error_code,
                                        const std::string& error_text,
                                        pthread_mutex_t* mutex);
 int bthread_id_list_reset2_bthreadsafe(bthread_id_list_t* list, int error_code,
                                        const std::string& error_text,
                                        bthread_mutex_t* mutex);
 #endif

 #endif  // BTHREAD_ID_H
	// Licensed to the Apache Software Foundation (ASF) under one
	// or more contributor license agreements. See the NOTICE file
	// distributed with this work for additional information
	// regarding copyright ownership. The ASF licenses this file
	// to you 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.

	// bthread - An M:N threading library to make applications more concurrent.

	// Date: Tue Jul 10 17:40:58 CST 2012

	#ifndef BTHREAD_ID_H
	#define BTHREAD_ID_H

	#include "butil/macros.h" // BAIDU_SYMBOLSTR
	#include "bthread/types.h"

	__BEGIN_DECLS

	// ----------------------------------------------------------------------
	// Functions to create 64-bit identifiers that can be attached with data
	// and locked without ABA issues. All functions can be called from
	// multiple threads simultaneously. Notice that bthread_id_t is designed
	// for managing a series of non-heavily-contended actions on an object.
	// It's slower than mutex and not proper for general synchronizations.
	// ----------------------------------------------------------------------

	// Create a bthread_id_t and put it into *id. Crash when `id' is NULL.
	// id->value will never be zero.
	// `on_error' will be called after bthread_id_error() is called.
	// -------------------------------------------------------------------------
	// ! User must call bthread_id_unlock() or bthread_id_unlock_and_destroy()
	// ! inside on_error.
	// -------------------------------------------------------------------------
	// Returns 0 on success, error code otherwise.
	int bthread_id_create(
	bthread_id_t* id, void* data,
	int (on_error)(bthread_id_t id, void data, int error_code));

	// When this function is called successfully, id, id+1 ... *id + range - 1
	// are mapped to same internal entity. Operations on any of the id work as
	// if they're manipulating a same id. `on_error' is called with the id issued
	// by corresponding bthread_id_error(). This is designed to let users encode
	// versions into identifiers.
	// `range' is limited inside [1, 1024].
	int bthread_id_create_ranged(
	bthread_id_t* id, void* data,
	int (on_error)(bthread_id_t id, void data, int error_code),
	int range);

	// Wait until `id' being destroyed.
	// Waiting on a destroyed bthread_id_t returns immediately.
	// Returns 0 on success, error code otherwise.
	int bthread_id_join(bthread_id_t id);

	// Destroy a created but never-used bthread_id_t.
	// Returns 0 on success, EINVAL otherwise.
	int bthread_id_cancel(bthread_id_t id);

	// Issue an error to `id'.
	// If `id' is not locked, lock the id and run `on_error' immediately. Otherwise
	// `on_error' will be called with the error just before `id' being unlocked.
	// If `id' is destroyed, un-called on_error are dropped.
	// Returns 0 on success, error code otherwise.
	#define bthread_id_error(id, err) \
	bthread_id_error_verbose(id, err, __FILE__ ":" BAIDU_SYMBOLSTR(__LINE__))

	int bthread_id_error_verbose(bthread_id_t id, int error_code,
	const char *location);

	// Make other bthread_id_lock/bthread_id_trylock on the id fail, the id must
	// already be locked. If the id is unlocked later rather than being destroyed,
	// effect of this function is cancelled. This function avoids useless
	// waiting on a bthread_id which will be destroyed soon but still needs to
	// be joinable.
	// Returns 0 on success, error code otherwise.
	int bthread_id_about_to_destroy(bthread_id_t id);

	// Try to lock `id' (for using the data exclusively)
	// On success return 0 and set `pdata' with the `data' parameter to
	// bthread_id_create[_ranged], EBUSY on already locked, error code otherwise.
	int bthread_id_trylock(bthread_id_t id, void** pdata);

	// Lock `id' (for using the data exclusively). If `id' is locked
	// by others, wait until `id' is unlocked or destroyed.
	// On success return 0 and set `pdata' with the `data' parameter to
	// bthread_id_create[_ranged], error code otherwise.
	#define bthread_id_lock(id, pdata) \
	bthread_id_lock_verbose(id, pdata, __FILE__ ":" BAIDU_SYMBOLSTR(__LINE__))
	int bthread_id_lock_verbose(bthread_id_t id, void** pdata,
	const char *location);

	// Lock `id' (for using the data exclusively) and reset the range. If `id' is
	// locked by others, wait until `id' is unlocked or destroyed. if `range' is
	// smaller than the original range of this id, nothing happens about the range
	#define bthread_id_lock_and_reset_range(id, pdata, range) \
	bthread_id_lock_and_reset_range_verbose(id, pdata, range, \
	__FILE__ ":" BAIDU_SYMBOLSTR(__LINE__))
	int bthread_id_lock_and_reset_range_verbose(
	bthread_id_t id, void **pdata,
	int range, const char *location);

	// Unlock `id'. Must be called after a successful call to bthread_id_trylock()
	// or bthread_id_lock().
	// Returns 0 on success, error code otherwise.
	int bthread_id_unlock(bthread_id_t id);

	// Unlock and destroy `id'. Waiters blocking on bthread_id_join() or
	// bthread_id_lock() will wake up. Must be called after a successful call to
	// bthread_id_trylock() or bthread_id_lock().
	// Returns 0 on success, error code otherwise.
	int bthread_id_unlock_and_destroy(bthread_id_t id);

	// **************************************************************************
	// bthread_id_list_xxx functions are NOT thread-safe unless explicitly stated

	// Initialize a list for storing bthread_id_t. When an id is destroyed, it will
	// be removed from the list automatically.
	// The commented parameters are not used anymore and just kept to not break
	// compatibility.
	int bthread_id_list_init(bthread_id_list_t* list,
	unsigned /size/,
	unsigned /conflict_size/);
	// Destroy the list.
	void bthread_id_list_destroy(bthread_id_list_t* list);

	// Add a bthread_id_t into the list.
	int bthread_id_list_add(bthread_id_list_t* list, bthread_id_t id);

	// Swap internal fields of two lists.
	void bthread_id_list_swap(bthread_id_list_t* dest,
	bthread_id_list_t* src);

	// Issue error_code to all bthread_id_t inside `list' and clear `list'.
	// Notice that this function iterates all id inside the list and may call
	// on_error() of each valid id in-place, in another word, this thread-unsafe
	// function is not suitable to be enclosed within a lock directly.
	// To make the critical section small, swap the list inside the lock and
	// reset the swapped list outside the lock as follows:
	// bthread_id_list_t tmplist;
	// bthread_id_list_init(&tmplist, 0, 0);
	// LOCK;
	// bthread_id_list_swap(&tmplist, &the_list_to_reset);
	// UNLOCK;
	// bthread_id_list_reset(&tmplist, error_code);
	// bthread_id_list_destroy(&tmplist);
	int bthread_id_list_reset(bthread_id_list_t* list, int error_code);
	// Following 2 functions wrap above process.
	int bthread_id_list_reset_pthreadsafe(
	bthread_id_list_t* list, int error_code, pthread_mutex_t* mutex);
	int bthread_id_list_reset_bthreadsafe(
	bthread_id_list_t* list, int error_code, bthread_mutex_t* mutex);

	__END_DECLS

	#if defined(__cplusplus)
	// cpp specific API, with an extra `error_text' so that error information
	// is more comprehensive
	int bthread_id_create2(
	bthread_id_t* id, void* data,
	int (on_error)(bthread_id_t id, void data, int error_code,
	const std::string& error_text));
	int bthread_id_create2_ranged(
	bthread_id_t* id, void* data,
	int (on_error)(bthread_id_t id, void data, int error_code,
	const std::string& error_text),
	int range);
	#define bthread_id_error2(id, ec, et) \
	bthread_id_error2_verbose(id, ec, et, __FILE__ ":" BAIDU_SYMBOLSTR(__LINE__))
	int bthread_id_error2_verbose(bthread_id_t id, int error_code,
	const std::string& error_text,
	const char *location);
	int bthread_id_list_reset2(bthread_id_list_t* list, int error_code,
	const std::string& error_text);
	int bthread_id_list_reset2_pthreadsafe(bthread_id_list_t* list, int error_code,
	const std::string& error_text,
	pthread_mutex_t* mutex);
	int bthread_id_list_reset2_bthreadsafe(bthread_id_list_t* list, int error_code,
	const std::string& error_text,
	bthread_mutex_t* mutex);
	#endif

	#endif // BTHREAD_ID_H