/// See if this session object is coupled. If it is, return the session's ID.
ttl: Duration,
#[inline]pubfncoupled(&self)-> Option<&SessionID>
users: RwLock<Vec<UserID>>,
{
self.id.as_ref()
}
}
}
/// A lock to a `Session` object, temporarily preventing it's expiring TTL from destroying the underlying session object.
///
/// While this object is alive, its TTL expiring will not cause the session to be destroyed; however, it will still be removed from the `Sessions` container that created it, which will cause lookups for this `Session` to fail.
/// If the TTL expires while the object(s) of this lock are alive, the underlying session data will be destroyed once all `SessionLock`s refering to it have been dropped.
///
/// It is still possible to check if the TTL has expired using methods on the lock.
///
/// # Remarks
/// You should refrain from keeping `SessionLock`s alive longer than they need to be, as they cause the object to outlive its TTL, it could result in a potential security vulerability and/or memory leak (a leaked `SessionLock` will cause the session to valid forever, which is a huge security risk despite it being unable to be looked up).
///
/// However, if a lock is needed withing a request's context, it should be acquired as soon as possible to prevent any kind of data race that destroys the object while it's still technically find to use. This is a logical issue, not a memory safety one. It is still safe to defer the creation of locks to later on in the request's handler.
///
/// # Notes
/// This 'lock' does not cause any exclusion on waiting threads. It's not really a lock. It's (essentially) free to acquire and hold locks as long as you like, however if you keep a persistent `SessionLock` object, it may outlive its original TTL causing a potential security vulerability as well as a potential memory leak.
///
/// # Warnings
/// It is assumed that when session or session lock objects interact with a container that *it is the same container that was used to create the object*. It is the responsibility of the consumer of these APIs to ensure that a session does not access an unrelated container and the result is *logically undefined behaviour*.
/// If the session is flagged for destruction while the lock is held, it will still be removed from it's `Sessions` object container, and the actual session object will be destroyed when the lock is released.
/// A locked session that has been destroyed is able to re-add itself to a `Sessions` container.
}
///
/// # Notes
Poll::Ready(Ok(()))
/// This 'lock' does not cause any exclusion on waiting threads. It's not really a lock. It's (essentially) free to acquire and hold locks as long as you like, however if you keep a persistent `SessionLock` object, it may outlive its original TTL causing a potential security vulerability as well as a potential memory leak.
///
/// # Warnings
/// It is assumed that when session or session lock objects interact with a container that *it is the same container that was used to create the object*. It is the responsibility of the consumer of these APIs to ensure that a session does not access an unrelated container and the result is *logically undefined behaviour*.
/// Consume a strong session reference and start its ttl timer to remove itself from the container.
/// This spawns a new detached task that owns a `Weak` reference to the inner sessions map. If the `Sessions` container is dropped before this task completes, then nothing happens after the TTL expires.
/// The detached task does *not* prevent the `Sessions` object from being destroyed on drop.
///
/// # Locking
/// When the TTL of this session expires, and the `Sessions` container has not been dropped, then the container's write lock is acquired to remove the session from the container. The task completes immediately after, releasing the lock after the single remove operation.
#[deprecated = "Useless without immediately calling `session.lock()` to retrieve the newly generated ID, which is a performance hit and `session.lock()` may fail causing the new session to be unindexable. Use `SessionID::new()` and `insert_new_with_id` instead."]
/// Create and insert a new `Session` object with the provided session ID using the session control options provided by `cfg`.
///
/// After inserting into the container, the new `Session` object is returned.
///
/// # Locking
/// This method acquires the container's *write* lock when inserting the session into the container. It is release immediately after the single insert operation.
///
/// It is not guaranteed that this method will complete without yielding.
/// As no concurrent calls to this function (or any others on this object) are possible due to Rust's single mutable reference rule, the only contributors to causing this call to yield are detached TTL expiration tasks which will also acquire the *write* lock when the TTL expires.
///
/// # Notes
/// It is not guaranteed that the *first* call to `session.lock()` will succeed. The only case that will cause this to happen is with improporly configured session TTLs.
/// Upon the consumer of this API retrieving this return value, if operations on the object are needed at any point the caller's context, she should immediately call `session.lock()` to prevent improporly configured TTLs destroying the session before it's enabled to be used.
///
/// If this happens, the session creation attempt should be considered to have failed, the request should return an error, and a log should be outputted informing the user that she configured the Session control TTL incorrectly; this is a configuration error.
/// If this method returns `None` for a contextually valid session ID, then the session is invalid to create any *new* accessors to.
/// However, if the session object has been removed due to expired TTL or another kind of invalidation, it doesn't nessisarily mean the session object has been destroyed.
/// It may still be being used by another task or request.
/////////TODO: `Session` and `Sessions` need a whole rework. We can't be returning references that borrow this container, it will block all other consumers wanting to get their own session reference. Rewrite using `Arc<Session>`s instead of `Session` s.
