4 * Copyright(c) 2015 Intel Corporation. All rights reserved.
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions
11 * * Redistributions of source code must retain the above copyright
12 * notice, this list of conditions and the following disclaimer.
13 * * Redistributions in binary form must reproduce the above copyright
14 * notice, this list of conditions and the following disclaimer in
15 * the documentation and/or other materials provided with the
17 * * Neither the name of Intel Corporation nor the names of its
18 * contributors may be used to endorse or promote products derived
19 * from this software without specific prior written permission.
21 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
24 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
25 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
26 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
27 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
28 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
29 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
30 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
31 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
35 * Some portions of this software may have been derived from the
36 * https://github.com/halayli/lthread which carrys the following license.
38 * Copyright (C) 2012, Hasan Alayli <halayli@gmail.com>
40 * Redistribution and use in source and binary forms, with or without
41 * modification, are permitted provided that the following conditions
43 * 1. Redistributions of source code must retain the above copyright
44 * notice, this list of conditions and the following disclaimer.
45 * 2. Redistributions in binary form must reproduce the above copyright
46 * notice, this list of conditions and the following disclaimer in the
47 * documentation and/or other materials provided with the distribution.
49 * THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND
50 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
51 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
52 * ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
53 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
54 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
55 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
56 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
57 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
58 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
66 * @b EXPERIMENTAL: this API may change without prior notice
68 * This file contains the public API for the L-thread subsystem
70 * The L_thread subsystem provides a simple cooperative scheduler to
71 * enable arbitrary functions to run as cooperative threads within a
74 * The subsystem provides a P-thread like API that is intended to assist in
75 * reuse of legacy code written for POSIX p_threads.
77 * The L-thread subsystem relies on cooperative multitasking, as such
78 * an L-thread must possess frequent rescheduling points. Often these
79 * rescheduling points are provided transparently when the application
80 * invokes an L-thread API.
82 * In some applications it is possible that the program may enter a loop the
83 * exit condition for which depends on the action of another thread or a
84 * response from hardware. In such a case it is necessary to yield the thread
85 * periodically in the loop body, to allow other threads an opportunity to
86 * run. This can be done by inserting a call to lthread_yield() or
87 * lthread_sleep(n) in the body of the loop.
89 * If the application makes expensive / blocking system calls or does other
90 * work that would take an inordinate amount of time to complete, this will
91 * stall the cooperative scheduler resulting in very poor performance.
93 * In such cases an L-thread can be migrated temporarily to another scheduler
94 * running in a different P-thread on another core. When the expensive or
95 * blocking operation is completed it can be migrated back to the original
96 * scheduler. In this way other threads can continue to run on the original
97 * scheduler and will be completely unaffected by the blocking behaviour.
98 * To migrate an L-thread to another scheduler the API lthread_set_affinity()
101 * If L-threads that share data are running on the same core it is possible
102 * to design programs where mutual exclusion mechanisms to protect shared data
103 * can be avoided. This is due to the fact that the cooperative threads cannot
104 * preempt each other.
106 * There are two cases where mutual exclusion mechanisms are necessary.
108 * a) Where the L-threads sharing data are running on different cores.
109 * b) Where code must yield while updating data shared with another thread.
111 * The L-thread subsystem provides a set of mutex APIs to help with such
112 * scenarios, however excessive reliance on on these will impact performance
113 * and is best avoided if possible.
115 * L-threads can synchronise using a fast condition variable implementation
116 * that supports signal and broadcast. An L-thread running on any core can
117 * wait on a condition.
119 * L-threads can have L-thread local storage with an API modelled on either the
120 * P-thread get/set specific API or using PER_LTHREAD macros modelled on the
121 * RTE_PER_LCORE macros. Alternatively a simple user data pointer may be set
122 * and retrieved from a thread.
128 #include <sys/socket.h>
130 #include <netinet/in.h>
132 #include <rte_cycles.h>
137 struct lthread_mutex;
139 struct lthread_condattr;
140 struct lthread_mutexattr;
142 typedef void (*lthread_func_t) (void *);
145 * Define the size of stack for an lthread
146 * Then this is the size that will be allocated on lthread creation
147 * This is a fixed size and will not grow.
149 #define LTHREAD_MAX_STACK_SIZE (1024*64)
152 * Define the maximum number of TLS keys that can be created
155 #define LTHREAD_MAX_KEYS 1024
158 * Define the maximum number of attempts to destroy an lthread's
159 * TLS data on thread exit
161 #define LTHREAD_DESTRUCTOR_ITERATIONS 4
165 * Define the maximum number of lcores that will support lthreads
167 #define LTHREAD_MAX_LCORES RTE_MAX_LCORE
170 * How many lthread objects to pre-allocate as the system grows
171 * applies to lthreads + stacks, TLS, mutexs, cond vars.
173 * @see _lthread_alloc()
175 * @see _mutex_alloc()
178 #define LTHREAD_PREALLOC 100
181 * Set the number of schedulers in the system.
183 * This function may optionally be called before starting schedulers.
185 * If the number of schedulers is not set, or set to 0 then each scheduler
186 * will begin scheduling lthreads immediately it is started.
188 * If the number of schedulers is set to greater than 0, then each scheduler
189 * will wait until all schedulers have started before beginning to schedule
192 * If an application wishes to have threads migrate between cores using
193 * lthread_set_affinity(), or join threads running on other cores using
194 * lthread_join(), then it is prudent to set the number of schedulers to ensure
195 * that all schedulers are initialised beforehand.
198 * the number of schedulers in the system
200 * the number of schedulers in the system
202 int lthread_num_schedulers_set(int num);
205 * Return the number of schedulers currently running
207 * the number of schedulers in the system
209 int lthread_active_schedulers(void);
212 * Shutdown the specified scheduler
214 * This function tells the specified scheduler to
215 * exit if/when there is no more work to do.
217 * Note that although the scheduler will stop
218 * resources are not freed.
221 * The lcore of the scheduler to shutdown
226 void lthread_scheduler_shutdown(unsigned lcore);
229 * Shutdown all schedulers
231 * This function tells all schedulers including the current scheduler to
232 * exit if/when there is no more work to do.
234 * Note that although the schedulers will stop
235 * resources are not freed.
240 void lthread_scheduler_shutdown_all(void);
243 * Run the lthread scheduler
245 * Runs the lthread scheduler.
246 * This function returns only if/when all lthreads have exited.
247 * This function must be the main loop of an EAL thread.
253 void lthread_run(void);
258 * Creates an lthread and places it in the ready queue on a particular
261 * If no scheduler exists yet on the curret lcore then one is created.
264 * Pointer to an lthread pointer that will be initialized
266 * the lcore the thread should be started on or the current clore
267 * -1 the current lcore
268 * 0 - LTHREAD_MAX_LCORES any other lcore
269 * @param lthread_func
270 * Pointer to the function the for the thread to run
272 * Pointer to args that will be passed to the thread
276 * EAGAIN no resources available
277 * EINVAL NULL thread or function pointer, or lcore_id out of range
280 lthread_create(struct lthread **new_lt,
281 int lcore, lthread_func_t func, void *arg);
286 * Cancels an lthread and causes it to be terminated
287 * If the lthread is detached it will be freed immediately
288 * otherwise its resources will not be released until it is joined.
291 * Pointer to an lthread that will be cancelled
295 * EINVAL thread was NULL
297 int lthread_cancel(struct lthread *lt);
302 * Joins the current thread with the specified lthread, and waits for that
304 * Passes an optional pointer to collect returned data.
307 * Pointer to the lthread to be joined
309 * Pointer to pointer to collect returned data
313 * EINVAL lthread could not be joined.
315 int lthread_join(struct lthread *lt, void **ptr);
320 * Detaches the current thread
321 * On exit a detached lthread will be freed immediately and will not wait
322 * to be joined. The default state for a thread is not detached.
327 void lthread_detach(void);
332 * Terminate the current thread, optionally return data.
333 * The data may be collected by lthread_join()
335 * After calling this function the lthread will be suspended until it is
336 * joined. After it is joined then its resources will be freed.
339 * Pointer to pointer to data to be returned
344 void lthread_exit(void *val);
347 * Cause the current lthread to sleep for n nanoseconds
349 * The current thread will be suspended until the specified time has elapsed
350 * or has been exceeded.
352 * Execution will switch to the next lthread that is ready to run
355 * Number of nanoseconds to sleep
360 void lthread_sleep(uint64_t nsecs);
363 * Cause the current lthread to sleep for n cpu clock ticks
365 * The current thread will be suspended until the specified time has elapsed
366 * or has been exceeded.
368 * Execution will switch to the next lthread that is ready to run
371 * Number of clock ticks to sleep
376 void lthread_sleep_clks(uint64_t clks);
379 * Yield the current lthread
381 * The current thread will yield and execution will switch to the
382 * next lthread that is ready to run
387 void lthread_yield(void);
390 * Migrate the current thread to another scheduler
392 * This function migrates the current thread to another scheduler.
393 * Execution will switch to the next lthread that is ready to run on the
394 * current scheduler. The current thread will be resumed on the new scheduler.
397 * The lcore to migrate to
400 * 0 success we are now running on the specified core
401 * EINVAL the destination lcore was not valid
403 int lthread_set_affinity(unsigned lcore);
406 * Return the current lthread
408 * Returns the current lthread
411 * pointer to the current lthread
414 *lthread_current(void);
417 * Associate user data with an lthread
419 * This function sets a user data pointer in the current lthread
420 * The pointer can be retrieved with lthread_get_data()
421 * It is the users responsibility to allocate and free any data referenced
422 * by the user pointer.
425 * pointer to user data
430 void lthread_set_data(void *data);
433 * Get user data for the current lthread
435 * This function returns a user data pointer for the current lthread
436 * The pointer must first be set with lthread_set_data()
437 * It is the users responsibility to allocate and free any data referenced
438 * by the user pointer.
441 * pointer to user data
444 *lthread_get_data(void);
447 typedef void (*tls_destructor_func) (void *);
450 * Create a key for lthread TLS
452 * This function is modelled on pthread_key_create
453 * It creates a thread-specific data key visible to all lthreads on the
456 * Key values may be used to locate thread-specific data.
457 * The same key value may be used by different threads, the values bound
458 * to the key by lthread_setspecific() are maintained on a per-thread
459 * basis and persist for the life of the calling thread.
461 * An optional destructor function may be associated with each key value.
462 * At thread exit, if a key value has a non-NULL destructor pointer, and the
463 * thread has a non-NULL value associated with the key, the function pointed
464 * to is called with the current associated value as its sole argument.
467 * Pointer to the key to be created
469 * Pointer to destructor function
473 * EINVAL the key ptr was NULL
474 * EAGAIN no resources available
476 int lthread_key_create(unsigned int *key, tls_destructor_func destructor);
479 * Delete key for lthread TLS
481 * This function is modelled on pthread_key_delete().
482 * It deletes a thread-specific data key previously returned by
483 * lthread_key_create().
484 * The thread-specific data values associated with the key need not be NULL
485 * at the time that lthread_key_delete is called.
486 * It is the responsibility of the application to free any application
487 * storage or perform any cleanup actions for data structures related to the
488 * deleted key. This cleanup can be done either before or after
489 * lthread_key_delete is called.
492 * The key to be deleted
496 * EINVAL the key was invalid
498 int lthread_key_delete(unsigned int key);
503 * This function is modelled on pthread_get_specific().
504 * It returns the value currently bound to the specified key on behalf of the
505 * calling thread. Calling lthread_getspecific() with a key value not
506 * obtained from lthread_key_create() or after key has been deleted with
507 * lthread_key_delete() will result in undefined behaviour.
508 * lthread_getspecific() may be called from a thread-specific data destructor
512 * The key for which data is requested
515 * Pointer to the thread specific data associated with that key
516 * or NULL if no data has been set.
519 *lthread_getspecific(unsigned int key);
524 * This function is modelled on pthread_set_sepcific()
525 * It associates a thread-specific value with a key obtained via a previous
526 * call to lthread_key_create().
527 * Different threads may bind different values to the same key. These values
528 * are typically pointers to dynamically allocated memory that have been
529 * reserved by the calling thread. Calling lthread_setspecific with a key
530 * value not obtained from lthread_key_create or after the key has been
531 * deleted with lthread_key_delete will result in undefined behaviour.
534 * The key for which data is to be set
536 * Pointer to the user data
540 * EINVAL the key was invalid
543 int lthread_setspecific(unsigned int key, const void *value);
546 * The macros below provide an alternative mechanism to access lthread local
549 * The macros can be used to declare define and access per lthread local
550 * storage in a similar way to the RTE_PER_LCORE macros which control storage
553 * Memory for per lthread variables declared in this way is allocated when the
554 * lthread is created and a pointer to this memory is stored in the lthread.
555 * The per lthread variables are accessed via the pointer + the offset of the
556 * particular variable.
558 * The total size of per lthread storage, and the variable offsets are found by
559 * defining the variables in a unique global memory section, the start and end
560 * of which is known. This global memory section is used only in the
561 * computation of the addresses of the lthread variables, and is never actually
562 * used to store any data.
564 * Due to the fact that variables declared this way may be scattered across
565 * many files, the start and end of the section and variable offsets are only
566 * known after linking, thus the computation of section size and variable
567 * addresses is performed at run time.
569 * These macros are primarily provided to aid porting of code that makes use
570 * of the existing RTE_PER_LCORE macros. In principle it would be more efficient
571 * to gather all lthread local variables into a single structure and
572 * set/retrieve a pointer to that struct using the alternative
573 * lthread_data_set/get APIs.
575 * These macros are mutually exclusive with the lthread_data_set/get APIs.
576 * If you define storage using these macros then the lthread_data_set/get APIs
577 * will not perform as expected, the lthread_data_set API does nothing, and the
578 * lthread_data_get API returns the start of global section.
581 /* start and end of per lthread section */
582 extern char __start_per_lt;
583 extern char __stop_per_lt;
586 #define RTE_DEFINE_PER_LTHREAD(type, name) \
587 __typeof__(type)__attribute((section("per_lt"))) per_lt_##name
590 * Macro to declare an extern per lthread variable "var" of type "type"
592 #define RTE_DECLARE_PER_LTHREAD(type, name) \
593 extern __typeof__(type)__attribute((section("per_lt"))) per_lt_##name
596 * Read/write the per-lcore variable value
598 #define RTE_PER_LTHREAD(name) ((typeof(per_lt_##name) *)\
599 ((char *)lthread_get_data() +\
600 ((char *) &per_lt_##name - &__start_per_lt)))
605 * This function provides a mutual exclusion device, the need for which
606 * can normally be avoided in a cooperative multitasking environment.
607 * It is provided to aid porting of legacy code originally written for
608 * preemptive multitasking environments such as pthreads.
610 * A mutex may be unlocked (not owned by any thread), or locked (owned by
613 * A mutex can never be owned by more than one thread simultaneously.
614 * A thread attempting to lock a mutex that is already locked by another
615 * thread is suspended until the owning thread unlocks the mutex.
617 * lthread_mutex_init() initializes the mutex object pointed to by mutex
618 * Optional mutex attributes specified in mutexattr, are reserved for future
619 * use and are currently ignored.
621 * If a thread calls lthread_mutex_lock() on the mutex, then if the mutex
622 * is currently unlocked, it becomes locked and owned by the calling
623 * thread, and lthread_mutex_lock returns immediately. If the mutex is
624 * already locked by another thread, lthread_mutex_lock suspends the calling
625 * thread until the mutex is unlocked.
627 * lthread_mutex_trylock behaves identically to rte_thread_mutex_lock, except
628 * that it does not block the calling thread if the mutex is already locked
631 * lthread_mutex_unlock() unlocks the specified mutex. The mutex is assumed
632 * to be locked and owned by the calling thread.
634 * lthread_mutex_destroy() destroys a mutex object, freeing its resources.
635 * The mutex must be unlocked with nothing blocked on it before calling
636 * lthread_mutex_destroy.
639 * Optional pointer to string describing the mutex
641 * Pointer to pointer to the mutex to be initialized
643 * Pointer to attribute - unused reserved
647 * EINVAL mutex was not a valid pointer
648 * EAGAIN insufficient resources
652 lthread_mutex_init(char *name, struct lthread_mutex **mutex,
653 const struct lthread_mutexattr *attr);
658 * This function destroys the specified mutex freeing its resources.
659 * The mutex must be unlocked before calling lthread_mutex_destroy.
661 * @see lthread_mutex_init()
664 * Pointer to pointer to the mutex to be initialized
668 * EINVAL mutex was not an initialized mutex
669 * EBUSY mutex was still in use
671 int lthread_mutex_destroy(struct lthread_mutex *mutex);
676 * This function attempts to lock a mutex.
677 * If a thread calls lthread_mutex_lock() on the mutex, then if the mutex
678 * is currently unlocked, it becomes locked and owned by the calling
679 * thread, and lthread_mutex_lock returns immediately. If the mutex is
680 * already locked by another thread, lthread_mutex_lock suspends the calling
681 * thread until the mutex is unlocked.
683 * @see lthread_mutex_init()
686 * Pointer to pointer to the mutex to be initialized
690 * EINVAL mutex was not an initialized mutex
691 * EDEADLOCK the mutex was already owned by the calling thread
694 int lthread_mutex_lock(struct lthread_mutex *mutex);
697 * Try to lock a mutex
699 * This function attempts to lock a mutex.
700 * lthread_mutex_trylock behaves identically to rte_thread_mutex_lock, except
701 * that it does not block the calling thread if the mutex is already locked
705 * @see lthread_mutex_init()
708 * Pointer to pointer to the mutex to be initialized
712 * EINVAL mutex was not an initialized mutex
713 * EBUSY the mutex was already locked by another thread
715 int lthread_mutex_trylock(struct lthread_mutex *mutex);
720 * This function attempts to unlock the specified mutex. The mutex is assumed
721 * to be locked and owned by the calling thread.
723 * The oldest of any threads blocked on the mutex is made ready and may
724 * compete with any other running thread to gain the mutex, it fails it will
728 * Pointer to pointer to the mutex to be initialized
731 * 0 mutex was unlocked
732 * EINVAL mutex was not an initialized mutex
733 * EPERM the mutex was not owned by the calling thread
736 int lthread_mutex_unlock(struct lthread_mutex *mutex);
739 * Initialize a condition variable
741 * This function initializes a condition variable.
743 * Condition variables can be used to communicate changes in the state of data
744 * shared between threads.
746 * @see lthread_cond_wait()
749 * Pointer to optional string describing the condition variable
751 * Pointer to pointer to the condition variable to be initialized
753 * Pointer to optional attribute reserved for future use, currently ignored
757 * EINVAL cond was not a valid pointer
758 * EAGAIN insufficient resources
761 lthread_cond_init(char *name, struct lthread_cond **c,
762 const struct lthread_condattr *attr);
765 * Destroy a condition variable
767 * This function destroys a condition variable that was created with
768 * lthread_cond_init() and releases its resources.
771 * Pointer to pointer to the condition variable to be destroyed
775 * EBUSY condition variable was still in use
776 * EINVAL was not an initialised condition variable
778 int lthread_cond_destroy(struct lthread_cond *cond);
781 * Wait on a condition variable
783 * The function blocks the current thread waiting on the condition variable
784 * specified by cond. The waiting thread unblocks only after another thread
785 * calls lthread_cond_signal, or lthread_cond_broadcast, specifying the
786 * same condition variable.
789 * Pointer to pointer to the condition variable to be waited on
792 * reserved for future use
795 * 0 The condition was signalled ( Success )
796 * EINVAL was not a an initialised condition variable
798 int lthread_cond_wait(struct lthread_cond *c, uint64_t reserved);
801 * Signal a condition variable
803 * The function unblocks one thread waiting for the condition variable cond.
804 * If no threads are waiting on cond, the rte_lthead_cond_signal() function
808 * Pointer to pointer to the condition variable to be signalled
811 * 0 The condition was signalled ( Success )
812 * EINVAL was not a an initialised condition variable
814 int lthread_cond_signal(struct lthread_cond *c);
817 * Broadcast a condition variable
819 * The function unblocks all threads waiting for the condition variable cond.
820 * If no threads are waiting on cond, the rte_lthead_cond_broadcast()
821 * function has no effect.
824 * Pointer to pointer to the condition variable to be signalled
827 * 0 The condition was signalled ( Success )
828 * EINVAL was not a an initialised condition variable
830 int lthread_cond_broadcast(struct lthread_cond *c);
832 #endif /* LTHREAD_H */