Drizzled Public API Documentation

drizzled::Session Class Reference

#include <session.h>

Inheritance diagram for drizzled::Session:
drizzled::Open_tables_state

List of all members.

Classes

class  impl_c

Public Types

enum  global_read_lock_t { NONE = 0, GOT_GLOBAL_READ_LOCK = 1, MADE_GLOBAL_READ_LOCK_BLOCK_COMMIT = 2 }
enum  killed_state_t {
  NOT_KILLED, KILL_BAD_DATA, KILL_CONNECTION, KILL_QUERY,
  KILLED_NO_VALUE
}
typedef boost::shared_ptr
< Session
shared_ptr
typedef Sessionreference
typedef const Sessionconst_reference
typedef const Sessionconst_pointer
typedef Sessionpointer
typedef boost::shared_ptr
< const std::string > 
QueryString
typedef boost::unordered_map
< std::string, user_var_entry
*, util::insensitive_hash,
util::insensitive_equal_to
UserVars

Public Member Functions

void * calloc (size_t size)
char * strmake (const char *str, size_t size)
void * memdup_w_gap (const void *str, size_t size, uint32_t gap)
void free_items ()
memory::RootgetMemRoot ()
uint64_t getXaId ()
void setXaId (uint64_t in_xa_id)
const LEX & lex () const
LEX & lex ()
enum_sql_command getSqlCommand () const
QueryString getQueryString () const
void resetQueryString ()
const char * getQueryStringCopy (size_t &length)
session::State::const_shared_ptr state ()
util::string::const_shared_ptr schema () const
void setClient (plugin::Client *client_arg)
plugin::ClientgetClient ()
plugin::ClientgetClient () const
const UserVars & getUserVariables () const
enum_tx_isolation getTxIsolation ()
identifier::User::const_shared_ptr user () const
void setUser (identifier::User::shared_ptr arg)
int32_t getScoreboardIndex ()
void setScoreboardIndex (int32_t in_scoreboard_index)
bool isViewable (identifier::User::const_reference) const
const char * where ()
void setWhere (const char *arg)
boost_thread_shared_ptr & getThread ()
void pushInterrupt (boost::this_thread::disable_interruption *interrupt_arg)
boost::this_thread::disable_interruption & getThreadInterupt ()
internal::st_my_thread_vargetThreadVar ()
void resetUserTime ()
const boost::posix_time::ptime & start_timer () const
void getTimeDifference (boost::posix_time::time_duration &result_arg, const boost::posix_time::ptime &arg) const
void ** getEngineData (const plugin::MonitoredInTransaction *monitored)
ResourceContextgetResourceContext (const plugin::MonitoredInTransaction *monitored, size_t index=0)
void setConcurrentExecute (bool arg)
bool isConcurrentExecuteAllowed () const
int64_t rowCount () const
uint32_t getRowCount () const
global_read_lock_t isGlobalReadLock () const
void setGlobalReadLock (global_read_lock_t arg)
DrizzleLocklockTables (Table **tables, uint32_t count, uint32_t flags)
bool lockGlobalReadLock ()
bool lock_table_names (TableList *table_list)
bool lock_table_names_exclusively (TableList *table_list)
bool makeGlobalReadLockBlockCommit ()
bool abortLockForThread (Table *table)
bool wait_if_global_read_lock (bool abort_on_refresh, bool is_not_commit)
int lock_table_name (TableList *table_list)
void abortLock (Table *table)
void removeLock (Table *table)
void unlockReadTables (DrizzleLock *sql_lock)
void unlockSomeTables (Table **table, uint32_t count)
void unlockTables (DrizzleLock *sql_lock)
void startWaitingGlobalReadLock ()
void unlockGlobalReadLock ()
void setKilled (killed_state_t arg)
killed_state_t getKilled ()
volatile killed_state_t * getKilledPtr ()
bool doing_tablespace_operation ()
void setDoingTablespaceOperation (bool doing)
void set_proc_info (const char *info)
const char * get_proc_info () const
void setQueryId (query_id_t in_query_id)
query_id_t getQueryId () const
void setWarningQueryId (query_id_t in_query_id)
query_id_t getWarningQueryId () const
session_id_t getSessionId () const
uint32_t getServerId () const
my_xid getTransactionId ()
void record_first_successful_insert_id_in_cur_stmt (uint64_t id_arg)
uint64_t read_first_successful_insert_id_in_prev_stmt ()
void force_one_auto_inc_interval (uint64_t next_id)
 Session (plugin::Client *client_arg, catalog::Instance::shared_ptr catalog)
void cleanup ()
void cleanup_after_query ()
bool storeGlobals ()
void awake (Session::killed_state_t state_to_set)
bool initGlobals ()
void prepareForQueries ()
bool executeStatement ()
bool readAndStoreQuery (const char *in_packet, uint32_t in_packet_length)
bool endTransaction (enum enum_mysql_completiontype completion)
bool endActiveTransaction ()
bool startTransaction (start_transaction_option_t opt=START_TRANS_NO_OPTIONS)
void markTransactionForRollback (bool all)
bool authenticate ()
void run ()
const char * enter_cond (boost::condition_variable_any &cond, boost::mutex &mutex, const char *msg)
void exit_cond (const char *old_msg)
type::Time::epoch_t query_start ()
void set_time ()
void set_time (time_t t)
void set_time_after_lock ()
void set_end_timer ()
uint64_t getElapsedTime () const
type::Time::epoch_t getCurrentTimestamp (bool actual=true) const
type::Time::epoch_t getCurrentTimestampEpoch () const
type::Time::epoch_t getCurrentTimestampEpoch (type::Time::usec_t &fraction_arg) const
uint64_t found_rows () const
bool inTransaction () const
LEX_STRINGmake_lex_string (LEX_STRING *lex_str, const char *str, uint32_t length, bool allocate_lex_string)
LEX_STRINGmake_lex_string (LEX_STRING *lex_str, const std::string &str, bool allocate_lex_string)
int send_explain_fields (select_result *result)
void clear_error (bool full=false)
void clearDiagnostics ()
void fatal_error ()
bool is_error () const
const CHARSET_INFOcharset ()
void end_statement ()
int killed_errno () const
void send_kill_message () const
bool abortOnWarning ()
void setAbortOnWarning (bool arg)
void setAbort (bool arg)
void lockOnSys ()
void set_status_var_init ()
void set_db (const std::string &new_db)
bool copy_db_to (char **p_db, size_t *p_db_length)
void push_internal_handler (Internal_error_handler *handler)
virtual bool handle_error (drizzled::error_t sql_errno, const char *message, DRIZZLE_ERROR::enum_warning_level level)
void pop_internal_handler ()
void reset_for_next_command ()
void disconnect (enum error_t errcode=EE_OK)
bool checkUser (const std::string &passwd, const std::string &db)
uint64_t getConnectMicroseconds () const
uint64_t getConnectSeconds () const
message::TransactiongetTransactionMessage () const
message::StatementgetStatementMessage () const
message::ResultsetgetResultsetMessage () const
void setTransactionMessage (message::Transaction *in_message)
void setStatementMessage (message::Statement *in_message)
void setResultsetMessage (message::Resultset *in_message)
void resetResultsetMessage ()
plugin::EventObserverListgetSessionObservers ()
void setSessionObservers (plugin::EventObserverList *observers)
plugin::EventObserverListgetSchemaObservers (const std::string &db_name)
void setSchemaObservers (const std::string &db_name, plugin::EventObserverList *observers)
void my_ok (ha_rows affected_rows=0, ha_rows found_rows_arg=0, uint64_t passed_id=0, const char *message=NULL)
void my_eof ()
bool add_item_to_list (Item *item)
bool add_value_to_list (Item *value)
bool add_order_to_list (Item *item, bool asc)
bool add_group_to_list (Item *item, bool asc)
void refresh_status ()
user_var_entrygetVariable (LEX_STRING &name, bool create_if_not_exists)
user_var_entrygetVariable (const std::string &name, bool create_if_not_exists)
void setVariable (const std::string &name, const std::string &value)
void close_thread_tables ()
void close_old_data_files (bool morph_locks=false, bool send_refresh=false)
void close_open_tables ()
void close_data_files_and_morph_locks (const identifier::Table &identifier)
void close_tables_for_reopen (TableList **tables)
bool openTablesLock (TableList *tables)
int open_tables_from_list (TableList **start, uint32_t *counter, uint32_t flags=0)
TableopenTableLock (TableList *table_list, thr_lock_type lock_type)
TableopenTable (TableList *table_list, bool *refresh, uint32_t flags=0)
void unlink_open_table (Table *find)
void drop_open_table (Table *table, const identifier::Table &identifier)
void close_cached_table (Table *table)
table::Placeholdertable_cache_insert_placeholder (const identifier::Table &identifier)
bool lock_table_name_if_not_cached (const identifier::Table &identifier, Table **table)
session::TableMessagesgetMessageCache ()
bool reopen_tables ()
bool close_cached_tables (TableList *tables, bool wait_for_refresh, bool wait_for_placeholders)
void wait_for_condition (boost::mutex &mutex, boost::condition_variable_any &cond)
int setup_conds (TableList *leaves, COND **conds)
int lock_tables (TableList *tables, uint32_t count, bool *need_reopen)
drizzled::util::StorablegetProperty (const std::string &arg)
template<class T >
void setProperty (const std::string &arg, T *value)
plugin::StorageEnginegetDefaultStorageEngine ()
void get_xid (DrizzleXid *xid)
table::SingulargetInstanceTable ()
table::SingulargetInstanceTable (List< CreateField > &field_list)
void setUsage (bool arg)
const rusage & getUsage ()
catalog::Instance::const_reference catalog () const
catalog::Instance::reference catalog ()
TablegetTemporaryTables ()
void mark_temp_tables_as_free_for_reuse ()
void close_temporary_table (Table *table)
Tablefind_temporary_table (const identifier::Table &identifier)
void dumpTemporaryTableNames (const char *id)
int drop_temporary_table (const drizzled::identifier::Table &identifier)
bool rm_temporary_table (plugin::StorageEngine *base, const identifier::Table &identifier)
bool rm_temporary_table (const drizzled::identifier::Table &identifier, bool best_effort=false)
Tableopen_temporary_table (const drizzled::identifier::Table &identifier, bool link_in_list=true)
TablegetDerivedTables ()
void setDerivedTables (Table *arg)
void clearDerivedTables ()
void doGetTableNames (CachedDirectory &directory, const identifier::Schema &schema_identifier, std::set< std::string > &set_of_names)
void doGetTableNames (const identifier::Schema &schema_identifier, std::set< std::string > &set_of_names)
void doGetTableIdentifiers (CachedDirectory &directory, const identifier::Schema &schema_identifier, identifier::Table::vector &set_of_identifiers)
void doGetTableIdentifiers (const identifier::Schema &schema_identifier, identifier::Table::vector &set_of_identifiers)
int doGetTableDefinition (const drizzled::identifier::Table &identifier, message::Table &table_proto)
bool doDoesTableExist (const drizzled::identifier::Table &identifier)

Static Public Member Functions

static shared_ptr make_shared (plugin::Client *client, catalog::Instance::shared_ptr instance_arg)
static bool schedule (Session::shared_ptr &)
static void unlink (session_id_t &session_id)
static void unlink (Session::shared_ptr &)

Public Attributes

enum enum_mark_columns mark_used_columns
Itemfree_list
memory::Rootmem_root
std::string query_cache_key
memory::Root warn_root
plugin::Schedulerscheduler
void * scheduler_arg
drizzle_system_variables variables
system_status_var status_var
THR_LOCK_INFO lock_info
THR_LOCK_OWNER main_lock_id
THR_LOCK_OWNERlock_id
char * thread_stack
uint32_t dbug_sentry
enum enum_server_command command
uint32_t file_id
uint32_t max_client_packet_length
uint64_t utime_after_lock
thr_lock_type update_lock_default
session::Transactions transaction
Fielddup_field
sigset_t signals
uint64_t first_successful_insert_id_in_prev_stmt
uint64_t first_successful_insert_id_in_cur_stmt
Discrete_intervals_list auto_inc_intervals_in_cur_stmt_for_binlog
Discrete_intervals_list auto_inc_intervals_forced
uint64_t limit_found_rows
uint64_t options
int64_t row_count_func
ha_rows cuted_fields
ha_rows sent_row_count
ha_rows examined_row_count
table_map used_tables
List< DRIZZLE_ERRORwarn_list
uint32_t warn_count [(uint32_t) DRIZZLE_ERROR::WARN_LEVEL_END]
uint32_t total_warn_count
Diagnostics_area main_da
ulong col_access
uint32_t statement_id_counter
uint32_t rand_saved_seed1
uint32_t rand_saved_seed2
uint32_t row_count
session_id_t thread_id
uint32_t tmp_table
uint32_t server_status
uint32_t open_options
uint32_t select_number
enum_tx_isolation session_tx_isolation
enum_check_fields count_cuted_fields
bool is_admin_connection
bool some_tables_deleted
bool no_errors
bool password
bool is_fatal_error
bool transaction_rollback_request
bool is_fatal_sub_stmt_error
bool substitute_null_with_insert_id
bool cleanup_done
bool got_warning
bool no_warnings_for_error
bool derived_tables_processing
union {
   bool   bool_value
   uint32_t   uint32_t_value
   int32_t   int32_t_value
   uint64_t   uint64_t_value
sys_var_tmp
Lex_input_streamm_lip
void * session_marker
Tablecached_table
bool arg_of_last_insert_id_function
Tableopen_tables
DrizzleLocklock
DrizzleLockextra_lock
uint64_t version
uint32_t current_tablenr

Static Public Attributes

static const char *const DEFAULT_WHERE = "field list"

Protected Member Functions

void close_temporary_tables ()

Private Types

typedef std::pair
< UserVars::iterator,
UserVars::iterator > 
UserVarsRange
typedef std::map< std::string,
plugin::EventObserverList * > 
schema_event_observers_t

Private Member Functions

void checkSentry () const
int unlock_external (Table **table, uint32_t count)
int lock_external (Table **tables, uint32_t count)
bool wait_for_locked_table_names (TableList *table_list)
DrizzleLockget_lock_data (Table **table_ptr, uint32_t count, bool should_lock, Table **write_lock_used)
void mark_used_tables_as_free_for_reuse (Table *table)
bool free_cached_table (boost::mutex::scoped_lock &scopedLock)
bool resetUsage ()

Private Attributes

boost::shared_ptr< std::string > query
session::State::shared_ptr _state
util::string::shared_ptr _schema
plugin::Clientclient
UserVars user_vars
identifier::User::shared_ptr security_ctx
int32_t scoreboard_index
const char * _where
boost::thread::id boost_thread_id
boost_thread_shared_ptr _thread
boost::this_thread::disable_interruption * interrupt
internal::st_my_thread_varmysys_var
boost::posix_time::ptime _epoch
boost::posix_time::ptime _connect_time
boost::posix_time::ptime _start_timer
boost::posix_time::ptime _end_timer
boost::posix_time::ptime _user_time
std::vector< Ha_dataha_data
query_id_t query_id
query_id_t warn_query_id
global_read_lock_t _global_read_lock
killed_state_t volatile _killed
Internal_error_handlerm_internal_handler
memory::Root main_mem_root
session::TableMessages _table_message_cache
boost::scoped_ptr< impl_cimpl_
catalog::Instance::shared_ptr _catalog
message::Transactiontransaction_message
message::Statementstatement_message
message::Resultsetresultset
plugin::EventObserverListsession_event_observers
schema_event_observers_t schema_event_observers
uint64_t xa_id
const char * proc_info
bool abort_on_warning
bool concurrent_execute_allowed
bool tablespace_op
bool use_usage
session::PropertyMap life_properties
std::vector< table::Singular * > temporary_shares
rusage usage

Detailed Description

Represents a client connection to the database server.

Contains the client/server protocol object, the current statement being executed, local-to-session variables and status counters, and a host of other information.

Todo:

The Session class should have a vector of Statement object pointers which comprise the statements executed on the Session. Until this architectural change is done, we can forget about parallel operations inside a session.

Todo:

Make member variables private and have inlined accessors and setters. Hide all member variables that are not critical to non-internal operations of the session object.

Definition at line 138 of file session.h.


Member Typedef Documentation

typedef boost::shared_ptr<const std::string> drizzled::Session::QueryString

query associated with this statement

Definition at line 216 of file session.h.


Member Function Documentation

Authenticates users, with error reporting.

Returns true on success, or false on failure.

Definition at line 694 of file session.cc.

References drizzled::plugin::Client::authenticate(), client, and status_var.

Referenced by run().

bool drizzled::Session::checkUser ( const std::string &  passwd,
const std::string &  db 
)

Check if user exists and the password supplied is correct.

Returns true on success, and false on failure.

Note:
Host, user and passwd may point to communication buffer. Current implementation does not depend on that, but future changes should be done with this in mind;
Parameters:
passwdScrambled password received from client
dbDatabase name to connect to, may be NULL

Definition at line 704 of file session.cc.

References my_ok(), and status_var.

Cleans up after query.

This function is used to reset thread data to its default state.

This function is not suitable for setting thread data to some non-default values, as there is only one replication thread, so different master threads may overwrite data of each other on slave.

Definition at line 894 of file session.cc.

References _where, auto_inc_intervals_in_cur_stmt_for_binlog, DEFAULT_WHERE, first_successful_insert_id_in_cur_stmt, first_successful_insert_id_in_prev_stmt, free_items(), and substitute_null_with_insert_id.

Referenced by drizzled::parse().

void drizzled::Session::clear_error ( bool  full = false) [inline]

Clear the current error, if any. We do not clear is_fatal_error or is_fatal_sub_stmt_error since we assume this is never called if the fatal error is set.

Todo:
: To silence an error, one should use Internal_error_handler mechanism. In future this function will be removed.

Definition at line 1109 of file session.h.

Referenced by executeStatement(), and reset_for_next_command().

Close all instances of a table open by this thread and replace them with exclusive name-locks.

Parameters:
sessionThread context
dbDatabase name for the table to be closed
table_nameName of the table to be closed
Note:
This function assumes that if we are not under LOCK TABLES, then there is only one table open and locked. This means that the function probably has to be adjusted before it can be used anywhere outside ALTER Table.
Must not use TableShare::table_name/db of the table being closed, the strings are used in a loop even after the share may be freed.

Definition at line 1225 of file sql_base.cc.

Referenced by drizzled::internal_alter_table().

void drizzled::Session::close_old_data_files ( bool  morph_locks = false,
bool  send_refresh = false 
)

Close handlers for tables in list, but leave the Table structure intact so that we can re-open these quickly.

Parameters:
sessionThread context
tableHead of the list of Table objects
morph_lockstrue - remove locks which we have on tables being closed but ensure that no DML or DDL will sneak in before we will re-open the table (i.e. temporarily morph our table-level locks into name-locks). false - otherwise
send_refreshShould we awake waiters even if we didn't close any tables?

Definition at line 1364 of file sql_base.cc.

References drizzled::Table::db_stat, and drizzled::Table::lock_count.

Auxiliary function to close all tables in the open_tables list.

Parameters:
sessionThread context.
Remarks:
It should not ordinarily be called directly.

Definition at line 383 of file sql_base.cc.

Referenced by close_thread_tables().

Prepares statement for reopening of tables and recalculation of set of prelocked tables.

Parameters:
Pointerto a pointer to a list of tables which we were trying to open and lock

Definition at line 1969 of file session.cc.

References close_thread_tables(), and drizzled::TableList::next_global.

Referenced by openTablesLock().

void drizzled::Session::disconnect ( enum error_t  errcode = EE_OK)

Disconnects the session from a client connection and updates any status variables necessary.

Parameters:
errcodeError code to print to console
Note:
For the connection that is doing shutdown, this is called twice

Definition at line 1696 of file session.cc.

References client, drizzled::plugin::Client::close(), drizzled::plugin::Client::isConnected(), status_var, and variables.

Referenced by initGlobals(), and run().

void drizzled::Session::drop_open_table ( Table table,
const identifier::Table identifier 
)

Auxiliary routine which closes and drops open table.

Parameters:
sessionThread handle
tableTable object for table to be dropped
db_nameName of database for this table
table_nameName of this table
Note:
This routine assumes that table to be closed is open only by calling thread so we needn't wait until other threads will close the table. Also unless called under implicit or explicit LOCK TABLES mode it assumes that table to be dropped is already unlocked. In the former case it will also remove lock on the table. But one should not rely on this behaviour as it may change in future. Currently, however, this function is never called for a table that was locked with LOCK TABLES.

Definition at line 725 of file sql_base.cc.

Drop a temporary table.

Try to locate the table in the list of session->temporary_tables. If the table is found:

  • if the table is being used by some outer statement, fail.
  • if the table is in session->locked_tables, unlock it and remove it from the list of locked tables. Currently only transactional temporary tables are present in the locked_tables list.
  • Close the temporary table, remove its .FRM
  • remove the table from the list of temporary tables

This function is used to drop user temporary tables, as well as internal tables created in CREATE TEMPORARY TABLE ... SELECT or ALTER Table. Even though part of the work done by this function is redundant when the table is internal, as long as we link both internal and user temporary tables into the same session->temporary_tables list, it's impossible to tell here whether we're dealing with an internal or a user temporary table.

Return values:
0the table was found and dropped successfully.
1the table was not found in the list of temporary tables of this thread
-1the table is in use by a outer query

Definition at line 639 of file sql_base.cc.

void drizzled::Open_tables_state::dumpTemporaryTableNames ( const char *  foo) [inherited]
Note:
this will be removed, I am looking through Hudson to see if it is finding any tables that are missed during cleanup.

Definition at line 2051 of file session.cc.

Cleanup statement parse state (parse tree, lex) and execution state after execution of a non-prepared SQL statement.

Todo:

Move this to Statement::~Statement

Definition at line 1605 of file session.cc.

References resetResultsetMessage().

Referenced by drizzled::parse().

bool drizzled::Session::endTransaction ( enum enum_mysql_completiontype  completion)

Ends the current transaction and (maybe) begins the next.

Returns true if the transaction completed successfully, otherwise false.

Parameters:
Completiontype

Definition at line 796 of file session.cc.

References drizzled::TransactionServices::commitTransaction(), options, and drizzled::TransactionServices::singleton().

Executes a single statement received from the client connection.

Returns true if the statement was successful, or false otherwise.

Note:

For profiling to work, it must never be called recursively.

In MySQL, this used to be the do_command() C function whic accepted a single parameter of the THD pointer.

Definition at line 734 of file session.cc.

References clear_error(), client, command, drizzled::dispatch_command(), drizzled::plugin::Client::readCommand(), and drizzled::Diagnostics_area::reset_diagnostics_area().

Referenced by run().

void drizzled::Session::fatal_error ( ) [inline]

Mark the current error as fatal. Warning: this does not set any error, it sets a property of the error, so must be followed or prefixed with my_error().

Definition at line 1130 of file session.h.

void drizzled::Session::force_one_auto_inc_interval ( uint64_t  next_id) [inline]

Used by Intvar_log_event::do_apply_event() and by "SET INSERT_ID=#" (mysqlbinlog). We'll soon add a variant which can take many intervals in argument.

Definition at line 902 of file session.h.

bool drizzled::Session::free_cached_table ( boost::mutex::scoped_lock &  scopedLock) [private]

Frees all items attached to this Statement

Definition at line 322 of file session.cc.

References free_list.

Referenced by cleanup_after_query().

uint64_t drizzled::Session::getConnectMicroseconds ( ) const [inline]

Returns the timestamp (in microseconds) of when the Session connected to the server.

Definition at line 1271 of file session.h.

Return the default storage engine

Parameters:
getDefaultStorageEngine()
Returns:
pointer to plugin::StorageEngine

Definition at line 1518 of file session.h.

Referenced by drizzled::statement::CreateTable::execute().

table::Singular * drizzled::Session::getInstanceTable ( List< CreateField > &  field_list)

Create a reduced Table object with properly set up Field list from a list of field definitions.

The created table doesn't have a table Cursor associated with it, has no keys, no group/distinct, no copy_funcs array. The sole purpose of this Table object is to use the power of Field class to read/write data to/from table->getInsertRecord(). Then one can store the record in any container (RB tree, hash, etc). The table is created in Session mem_root, so are the table's fields. Consequently, if you don't BLOB fields, you don't need to free it.

Parameters:
sessionconnection handle
field_listlist of column definitions
Returns:
0 if out of memory, Table object in case of success

Definition at line 2111 of file session.cc.

Returns a pointer to the current Resulset message for this Session, or NULL if no active message.

Definition at line 1304 of file session.h.

Referenced by drizzled::QueryCacheService::addRecord(), and drizzled::QueryCacheService::setCurrentResultsetMessage().

uint32_t drizzled::Session::getServerId ( ) const [inline]

Accessor method returning the server's ID.

Definition at line 841 of file session.h.

Referenced by drizzled::TransactionServices::initTransactionMessage().

Returns the current transaction ID for the session's current statement

Definition at line 848 of file session.h.

Returns a pointer to the active Transaction message for this Session being managed by the ReplicationServices component, or NULL if no active message.

Definition at line 1286 of file session.h.

Referenced by drizzled::TransactionServices::commitTransactionMessage(), drizzled::TransactionServices::getActiveTransactionMessage(), and drizzled::TransactionServices::setSavepoint().

query_id_t drizzled::Session::getWarningQueryId ( ) const [inline]

Returns the Session's warning query ID

Definition at line 829 of file session.h.

bool drizzled::Session::handle_error ( drizzled::error_t  sql_errno,
const char *  message,
DRIZZLE_ERROR::enum_warning_level  level 
) [virtual]

Handle an error condition.

Parameters:
sql_errnothe error number
levelthe error level
Returns:
true if the error is handled

Definition at line 343 of file session.cc.

References drizzled::Internal_error_handler::handle_error(), and m_internal_handler.

Pulls thread-specific variables into Session state.

Returns true most times, or false if there was a problem allocating resources for thread-specific storage.

Kill this. It's not necessary once my_thr_init() is bye bye.

Definition at line 584 of file session.cc.

References disconnect(), and status_var.

Referenced by run().

bool drizzled::Session::inTransaction ( ) const [inline]

Returns whether the session is currently inside a transaction

Definition at line 1087 of file session.h.

Referenced by drizzled::statement::Truncate::execute(), and drizzled::execute_command().

bool drizzled::Session::is_error ( ) const [inline]

true if there is an error in the error stack.

Please use this method instead of direct access to net.report_error.

If true, the current (sub)-statement should be aborted. The main difference between this member and is_fatal_error is that a fatal error can not be handled by a stored procedure continue handler, whereas a normal error can.

To raise this flag, use my_error().

Definition at line 1148 of file session.h.

Referenced by close_thread_tables(), drizzled::copy_funcs(), drizzled::delete_query(), drizzled::dispatch_command(), drizzled::do_select(), drizzled::evaluate_join_record(), drizzled::Join::exec(), drizzled::execute_command(), drizzled::handle_select(), drizzled::insert_query(), drizzled::internal_alter_table(), drizzled::Join::optimize(), drizzled::parse(), drizzled::parse_sql(), drizzled::Join::prepare(), drizzled::select_query(), drizzled::sql_set_variables(), and drizzled::update_query().

Is this session viewable by the current user?

Definition at line 663 of file session.cc.

References drizzled::plugin::Authorization::isAuthorized().

bool drizzled::Session::lock_table_name_if_not_cached ( const identifier::Table identifier,
Table **  table 
)

Obtain an exclusive name lock on the table if it is not cached in the table cache.

Parameters:
sessionThread context
dbName of database
table_nameName of table
[out]tableOut parameter which is either:
  • set to NULL if table cache contains record for the table or
  • set to point to the Table instance used for name-locking.
Note:
This function takes into account all records for table in table cache, even placeholders used for name-locking. This means that 'table' parameter can be set to NULL for some situations when table does not really exist.
Return values:
trueError occured (OOM)
falseSuccess. 'table' parameter set according to above rules.

Definition at line 842 of file sql_base.cc.

Referenced by drizzled::drizzle_create_table().

LEX_STRING * drizzled::Session::make_lex_string ( LEX_STRING lex_str,
const std::string &  str,
bool  allocate_lex_string 
)

Create a LEX_STRING in this connection.

Parameters:
lex_strpointer to LEX_STRING object to be initialized
strinitializer to be copied into lex_str
lengthlength of str, in bytes
allocate_lex_stringif true, allocate new LEX_STRING object, instead of using lex_str value
Returns:
NULL on failure, or pointer to the LEX_STRING object

Definition at line 937 of file session.cc.

Mark all temporary tables which were used by the current statement or substatement as free for reuse, but only if the query_id can be cleared.

Parameters:
sessionthread context
Remarks:
For temp tables associated with a open SQL HANDLER the query_id is not reset until the HANDLER is closed.

Definition at line 1887 of file session.cc.

Referenced by close_thread_tables().

Marks all tables in the list which were used by current substatement as free for reuse.

Parameters:
Headof the list of tables
Note:

The reason we reset query_id is that it's not enough to just test if table->query_id != session->query_id to know if a table is in use.

For example

SELECT f1_that_uses_t1() FROM t1;

In f1_that_uses_t1() we will see one instance of t1 where query_id is set to query_id of original query.

Definition at line 1899 of file session.cc.

References drizzled::Table::cursor, getQueryId(), and drizzled::Cursor::ha_reset().

Mark transaction to rollback and mark error as fatal to a sub-statement.

Parameters:
sessionThread handle
alltrue <=> rollback main transaction().

Definition at line 1690 of file session.cc.

References is_fatal_sub_stmt_error, and transaction_rollback_request.

Referenced by convert_error_code_to_mysql().

void drizzled::Session::my_eof ( ) [inline]

A short cut for session->main_da.set_eof_status().

Definition at line 1423 of file session.h.

Referenced by drizzled::dispatch_command().

Open all tables in list, locks them (all, including derived)

Parameters:
Pointerto a list of tables for open & locking
Return values:
false- ok
true- error
Note:

The lock will automaticaly be freed by close_thread_tables()

Definition at line 1983 of file session.cc.

References close_tables_for_reopen().

Referenced by drizzled::delete_query(), drizzled::insert_query(), and drizzled::update_query().

Remove the error handler last pushed.

Definition at line 374 of file session.cc.

References m_internal_handler.

Initialize memory roots necessary for query processing and (!) pre-allocate memory for it. We can't do that in Session constructor because there are use cases where it's vital to not allocate excessive and not used memory.

Definition at line 566 of file session.cc.

References command, mem_root, options, drizzled::refresh_version, drizzled::memory::Root::reset_root_defaults(), set_proc_info(), and variables.

Referenced by run().

Add an internal error handler to the thread execution context.

Parameters:
handlerthe exception handler to add

Definition at line 333 of file session.cc.

References m_internal_handler.

bool drizzled::Session::readAndStoreQuery ( const char *  in_packet,
uint32_t  in_packet_length 
)

Reads a query from packet and stores it.

Returns true if query is read and allocated successfully, false otherwise. On a return of false, Session::fatal_error is set.

Note:
Used in COM_QUERY and COM_STMT_PREPARE.

Sets the following Session variables:

  • query
  • query_length
Parameters:
Thepacket pointer to read from
Thelength of the query to read

Definition at line 769 of file session.cc.

References _schema, and drizzled::plugin::QueryRewriter::rewriteQuery().

Referenced by drizzled::dispatch_command().

There is BUG#19630 where statement-based replication of stored functions/triggers with two auto_increment columns breaks. We however ensure that it works when there is 0 or 1 auto_increment column; our rules are a) on master, while executing a top statement involving substatements, first top- or sub- statement to generate auto_increment values wins the exclusive right to see its values be written to binlog (the write will be done by the statement or its caller), and the losers won't see their values be written to binlog. b) on slave, while replicating a top statement involving substatements, first top- or sub- statement to need to read auto_increment values from the master's binlog wins the exclusive right to read them (so the losers won't read their values from binlog but instead generate on their own). a) implies that we mustn't backup/restore auto_inc_intervals_in_cur_stmt_for_binlog. b) implies that we mustn't backup/restore auto_inc_intervals_forced.

If there are more than 1 auto_increment columns, then intervals for different columns may mix into the auto_inc_intervals_in_cur_stmt_for_binlog list, which is logically wrong, but there is no point in preventing this mixing by preventing intervals from the secondly inserted column to come into the list, as such prevention would be wrong too. What will happen in the case of INSERT INTO t1 (auto_inc) VALUES(NULL); where t1 has a trigger which inserts into an auto_inc column of t2, is that in binlog we'll store the interval of t1 and the interval of t2 (when we store intervals, soon), then in slave, t1 will use both intervals, t2 will use none; if t1 inserts the same number of rows as on master, normally the 2nd interval will not be used by t1, which is fine. t2's values will be wrong if t2's internal auto_increment counter is different from what it was on master (which is likely). In 5.1, in mixed binlogging mode, row-based binlogging is used for such cases where two auto_increment columns are inserted.

Definition at line 888 of file session.h.

Reopen all tables with closed data files.

Parameters:
sessionThread context
get_locksShould we get locks after reopening tables ?
mark_share_as_oldMark share as old to protect from a impending global read lock.
Note:
Since this function can't properly handle prelocking and create placeholders it should be used in very special situations like FLUSH TABLES or ALTER Table. In general case one should just repeat open_tables()/lock_tables() combination when one needs tables to be reopened (for example see openTablesLock()).
One should have lock on table::Cache::singleton().mutex() when calling this.
Returns:
false in case of success, true - otherwise.

Definition at line 1275 of file sql_base.cc.

Resets Session part responsible for command processing state.

This needs to be called before execution of every statement (prepared or conventional). It is not called by substatements of routines.

Todo:

Make it a method of Session and align its name with the rest of reset/end/start/init methods.

Call it after we use Session for queries, not before.

Definition at line 1733 of file session.cc.

References auto_inc_intervals_in_cur_stmt_for_binlog, clear_error(), examined_row_count, free_list, is_fatal_error, drizzled::Diagnostics_area::reset_diagnostics_area(), select_number, and sent_row_count.

Referenced by drizzled::parse().

reset the active Resultset message used by the Query Cache plugin.

Definition at line 1345 of file session.h.

Referenced by end_statement().

Run a session.

This will initialize the session and begin the command loop.

Definition at line 595 of file session.cc.

References authenticate(), client, disconnect(), executeStatement(), initGlobals(), and prepareForQueries().

bool drizzled::Session::schedule ( Session::shared_ptr &  arg) [static]

Schedule a session to be run on the default scheduler.

Definition at line 614 of file session.cc.

void drizzled::Session::set_db ( const std::string &  new_db)

Set the current database; use deep copy of C-string.

Parameters:
new_dba pointer to the new database name.
new_db_lenlength of the new database name.

Initialize the current database from a NULL-terminated string with length. If we run out of memory, we free the current database and return true. This way the user will notice the error as there will be no current database selected (in addition to the error message set by malloc).

Note:
This operation just sets {db, db_length}. Switching the current database usually involves other actions, like switching other database attributes including security context. In the future, this operation will be made private and more convenient interface will be provided.

Definition at line 1670 of file session.cc.

void drizzled::Session::set_proc_info ( const char *  info) [inline]

Points to info-string that we show in SHOW PROCESSLIST You are supposed to call Session_SET_PROC_INFO only if you have coded a time-consuming piece that MySQL can get stuck in for a long time.

Set it using the session_proc_info(Session *thread, const char *message) macro/function.

Definition at line 800 of file session.h.

Referenced by drizzled::delete_query(), drizzled::dispatch_command(), drizzled::Join::exec(), drizzled::execute_command(), drizzled::insert_query(), drizzled::internal_alter_table(), drizzled::Join::optimize(), drizzled::parse(), prepareForQueries(), drizzled::select_query(), and drizzled::update_query().

void drizzled::Session::setQueryId ( query_id_t  in_query_id) [inline]

Sets this Session's current query ID

Definition at line 810 of file session.h.

Referenced by drizzled::dispatch_command().

Sets the active Resultset message used by the Query Cache plugin.

Parameters:
[in]Pointerto the message

Definition at line 1336 of file session.h.

Referenced by drizzled::QueryCacheService::setCurrentResultsetMessage().

Sets the active transaction message used by the ReplicationServices component.

Parameters:
[in]Pointerto the message

Definition at line 1314 of file session.h.

Referenced by drizzled::TransactionServices::cleanupTransactionMessage(), and drizzled::TransactionServices::getActiveTransactionMessage().

void drizzled::Session::setWarningQueryId ( query_id_t  in_query_id) [inline]

Sets this Session's warning query ID

Definition at line 823 of file session.h.

Create and insert into table cache placeholder for table which will prevent its opening (or creation) (a.k.a lock table name).

Parameters:
sessionThread context
keyTable cache key for name to be locked
key_lengthTable cache key length
Returns:
Pointer to Table object used for name locking or 0 in case of failure.

Definition at line 800 of file sql_base.cc.

Remove all instances of table from thread's open list and table cache.

Parameters:
sessionThread context
findTable to remove
Note:
because we risk the chance of deleting the share, we can't assume that it will exist past, this should be modified once we can use a TableShare::shared_ptr here.

Definition at line 669 of file sql_base.cc.

Referenced by drizzled::drizzle_create_table(), and drizzled::internal_alter_table().


Member Data Documentation

util::string::shared_ptr drizzled::Session::_schema [private]

Name of the current (default) database.

If there is the current (default) database, "db" contains its name. If there is no current (default) database, "db" is NULL and "db_length" is 0. In other words, "db", "db_length" must either be NULL, or contain a valid database name.

Note:
this attribute is set and alloced by the slave SQL thread (for the Session of that thread); that thread is (and must remain, for now) the only responsible for freeing this member.

Definition at line 279 of file session.h.

Referenced by readAndStoreQuery().

const char* drizzled::Session::_where [private]

Used in error messages to tell user in what part of MySQL we found an error. E. g. when where= "having clause", if fix_fields() fails, user will know that the error was in having clause.

Definition at line 397 of file session.h.

Referenced by cleanup_after_query().

Used by replication and SET INSERT_ID

Definition at line 570 of file session.h.

Referenced by drizzled::Cursor::ha_release_auto_increment().

We follow this logic:

  • when stmt starts, first_successful_insert_id_in_prev_stmt contains the first insert id successfully inserted by the previous stmt.
  • as stmt makes progress, handler::insert_id_for_cur_row changes; every time get_auto_increment() is called, auto_inc_intervals_in_cur_stmt_for_binlog is augmented with the reserved interval (if statement-based binlogging).
  • at first successful insertion of an autogenerated value, first_successful_insert_id_in_cur_stmt is set to handler::insert_id_for_cur_row.
  • when stmt goes to binlog, auto_inc_intervals_in_cur_stmt_for_binlog is binlogged if non-empty.
  • when stmt ends, first_successful_insert_id_in_prev_stmt is set to first_successful_insert_id_in_cur_stmt.

List of auto_increment intervals reserved by the thread so far, for storage in the statement-based binlog. Note that its minimum is not first_successful_insert_id_in_cur_stmt: assuming a table with an autoinc column, and this happens: INSERT INTO ... VALUES(3); SET INSERT_ID=3; INSERT IGNORE ... VALUES (NULL); then the latter INSERT will insert no rows (first_successful_insert_id_in_cur_stmt == 0), but storing "INSERT_ID=3" in the binlog is still needed; the list's minimum will contain 3.

Definition at line 568 of file session.h.

Referenced by cleanup_after_query(), and reset_for_next_command().

Keeps a copy of the previous table around in case we are just slamming on particular table

Definition at line 790 of file session.h.

Pointer to client object

Definition at line 303 of file session.h.

Referenced by authenticate(), disconnect(), executeStatement(), and run().

enum enum_server_command drizzled::Session::command

Type of current query: COM_STMT_PREPARE, COM_QUERY, etc. Set from first byte of the packet in executeStatement()

Definition at line 450 of file session.h.

Referenced by drizzled::dispatch_command(), executeStatement(), and prepareForQueries().

Count of "cut" or truncated fields.

Todo:
Kill this friggin thing.

Definition at line 581 of file session.h.

Referenced by drizzled::insert_query(), drizzled::internal_alter_table(), drizzled::Field::set_warning(), drizzled::store_val_in_field(), and drizzled::update_query().

watch for memory corruption

Definition at line 415 of file session.h.

const char *const drizzled::Session::DEFAULT_WHERE = "field list" [static]

Constant for Session::where initialization in the beginning of every query.

It's needed because we do not save/restore Session::where normally during primary (non subselect) query execution.

Definition at line 299 of file session.h.

Referenced by cleanup_after_query().

set during loop of derived table processing

Definition at line 755 of file session.h.

Referenced by drizzled::Join::prepare().

Number of rows we read, sent or not, including in create_sort_index()

Definition at line 592 of file session.h.

Referenced by drizzled::Join::exec(), and reset_for_next_command().

File ID for LOAD DATA INFILE

Definition at line 451 of file session.h.

This is the first autogenerated insert id which was *successfully* inserted by the current statement. It is maintained only to set first_successful_insert_id_in_prev_stmt when statement ends.

Definition at line 540 of file session.h.

Referenced by cleanup_after_query(), and drizzled::insert_query().

This is the first autogenerated insert id which was *successfully* inserted by the previous statement (exactly, if the previous statement didn't successfully insert an autogenerated insert id, then it's the one of the statement before, etc). It can also be set by SET LAST_INSERT_ID=# or SELECT LAST_INSERT_ID(#). It is returned by LAST_INSERT_ID().

Definition at line 534 of file session.h.

Referenced by cleanup_after_query(), drizzled::insert_query(), drizzled::remove_eq_conds(), drizzled::update_query(), and drizzled::Item_func_last_insert_id::val_int().

List of items created in the parser for this query. Every item puts itself to the list on creation (see Item::Item() for details))

Definition at line 192 of file session.h.

Referenced by free_items(), drizzled::Item::Item(), and reset_for_next_command().

Set on call to push_warning()

Definition at line 752 of file session.h.

Referenced by drizzled::Field_decimal::store().

Set to true if execution of the current compound statement can not continue. In particular, disables activation of CONTINUE or EXIT handlers of stored routines. Reset in the end of processing of the current user request, in

See also:
reset_session_for_next_command().

Definition at line 728 of file session.h.

Referenced by drizzled::add_ref_to_table_cond(), drizzled::change_refs_to_tmp_fields(), drizzled::delete_query(), drizzled::Join::exec(), drizzled::subselect_hash_sj_engine::exec(), drizzled::find_order_in_list(), drizzled::Join::optimize(), drizzled::parse_sql(), reset_for_next_command(), and drizzle_plugin::ClientMySQLProtocol::writeEOFPacket().

true if we are in a sub-statement and the current error can not be safely recovered until we left the sub-statement mode. In particular, disables activation of CONTINUE and EXIT handlers inside sub-statements. E.g. if it is a deadlock error and requires a transaction-wide rollback, this flag is raised (traditionally, MySQL first has to close all the reads via

See also:
handler::ha_index_or_rnd_end() and only then perform the rollback). Reset to false when we leave the sub-statement mode.

Definition at line 746 of file session.h.

Referenced by markTransactionForRollback().

If not main_lock_id, points to the lock_id of a cursor.

Definition at line 344 of file session.h.

Locking information for this session

Definition at line 342 of file session.h.

The current internal error handler for this thread, or NULL.

Definition at line 1380 of file session.h.

Referenced by handle_error(), pop_internal_handler(), and push_internal_handler().

Character input stream consumed by the lexical analyser, used during parsing. Note that since the parser is not re-entrant, we keep only one input stream here. This member is valid only when executing code during parsing, and may point to invalid memory after that.

Definition at line 784 of file session.h.

Referenced by drizzled::check_simple_select(), and drizzled::parse_sql().

To use for conventional queries

Definition at line 343 of file session.h.

This memory root is used for two purposes:

  • for conventional queries, to allocate structures stored in main_lex during parsing, and allocate runtime data (execution plan, etc.) during execution.
  • for prepared queries, only to allocate runtime data. The parsed tree itself is reused between executions and thus is stored elsewhere.

Definition at line 1389 of file session.h.

Maximum number of bytes a client can send in a single packet

Definition at line 453 of file session.h.

Pointer to current memroot

Definition at line 193 of file session.h.

Referenced by drizzled::Create_udf_func::create(), drizzled::Create_func_bin::create(), drizzled::Create_func_conv::create(), drizzled::Create_func_cot::create(), drizzled::Create_func_date_format::create(), drizzled::Create_func_datediff::create(), drizzled::Create_func_dayname::create(), drizzled::Create_func_dayofmonth::create(), drizzled::Create_func_dayofweek::create(), drizzled::Create_func_dayofyear::create(), drizzled::Create_func_degrees::create(), drizzled::Create_func_find_in_set::create(), drizzled::Create_func_found_rows::create(), drizzled::Create_func_from_days::create(), drizzled::Create_func_ifnull::create(), drizzled::Create_func_instr::create(), drizzled::Create_func_isnull::create(), drizzled::Create_func_last_day::create(), drizzled::Create_func_lcase::create(), drizzled::Create_func_load_file::create(), drizzled::Create_func_lpad::create(), drizzled::Create_func_ltrim::create(), drizzled::Create_func_makedate::create(), drizzled::Create_func_monthname::create(), drizzled::Create_func_nullif::create(), drizzled::Create_func_oct::create(), drizzled::Create_func_period_add::create(), drizzled::Create_func_period_diff::create(), drizzled::Create_func_pi::create(), drizzled::Create_func_radians::create(), drizzled::Create_func_row_count::create(), drizzled::Create_func_rpad::create(), drizzled::Create_func_rtrim::create(), drizzled::Create_func_sign::create(), drizzled::Create_func_space::create(), drizzled::Create_func_strcmp::create(), drizzled::Create_func_tan::create(), drizzled::Create_func_time_format::create(), drizzled::Create_func_to_days::create(), drizzled::Create_func_ucase::create(), drizzled::Create_func_weekday::create(), drizzled::create_func_cast(), drizzled::Create_func_concat::create_native(), drizzled::Create_func_concat_ws::create_native(), drizzled::Create_func_export_set::create_native(), drizzled::Create_func_field::create_native(), drizzled::Create_func_from_unixtime::create_native(), drizzled::Create_func_greatest::create_native(), drizzled::Create_func_last_insert_id::create_native(), drizzled::Create_func_least::create_native(), drizzled::Create_func_locate::create_native(), drizzled::Create_func_make_set::create_native(), drizzled::Create_func_round::create_native(), drizzled::Create_func_unix_timestamp::create_native(), drizzled::create_tmp_field_from_field(), drizzled::TransactionServices::deleteRecord(), drizzled::dispatch_command(), drizzled::optimizer::QuickRangeSelect::init_ror_merged_scan(), drizzled::TransactionServices::insertRecord(), drizzled::prepare_create_table(), prepareForQueries(), drizzled::Join::rollup_init(), drizzled::Join::rollup_make_fields(), drizzled::setup_copy_fields(), and drizzled::TransactionServices::updateRecord().

no warnings on call to my_error()

Definition at line 753 of file session.h.

List of regular tables in use by this thread. Contains temporary and base tables that were opened with

See also:
open_tables().

Definition at line 44 of file open_tables_state.h.

Referenced by close_thread_tables().

Row counter, mainly for errors and warnings. Not increased in create_sort_index(); may differ from examined_row_count.

Definition at line 628 of file session.h.

Referenced by drizzled::Field_num::check_int(), drizzled::evaluate_join_record(), drizzled::insert_query(), drizzled::internal_alter_table(), drizzled::Field::set_warning(), drizzled::sub_select(), and drizzled::update_query().

Pointer to scheduler object

Definition at line 319 of file session.h.

Pointer to the optional scheduler argument

Definition at line 320 of file session.h.

number of select (used for EXPLAIN)

Definition at line 684 of file session.h.

Referenced by reset_for_next_command().

Number of rows we actually sent to the client, including "synthetic" rows in ROLLUP etc.

Definition at line 587 of file session.h.

Referenced by drizzled::Join::exec(), and reset_for_next_command().

Place to store various things

Definition at line 787 of file session.h.

Referenced by drizzled::handle_select().

for IS NULL => = last_insert_id() fix in remove_eq_conds()

Definition at line 748 of file session.h.

Referenced by cleanup_after_query(), and drizzled::remove_eq_conds().

Used by the sys_var class to store temporary values

This is true in DISCARD/IMPORT TABLESPACE

Definition at line 1580 of file session.h.

A pointer to the stack frame of the scheduler thread which is called first in the thread for handling a client

Definition at line 350 of file session.h.

Referenced by drizzled::check_stack_overrun().

Pointers to memory managed by the ReplicationServices component

Definition at line 1566 of file session.h.

Set by a storage engine to request the entire transaction (that possibly spans multiple engines) to rollback. Reset in ha_rollback.

Definition at line 734 of file session.h.

Referenced by drizzled::TransactionServices::autocommitOrRollback(), and markTransactionForRollback().

The set of those tables whose fields are referenced in all subqueries of the query.

Todo:

Possibly this it is incorrect to have used tables in Session because with more than one subquery, it is not clear what does the field mean.

Definition at line 603 of file session.h.

Referenced by drizzled::insert_query(), drizzled::Join::optimize(), and drizzled::select_query().

UserVars drizzled::Session::user_vars [private]

Hash of user variables defined during the session's lifetime

Definition at line 326 of file session.h.

Todo:

This, and some other variables like 'count_cuted_fields' maybe should be statement/cursor local, that is, moved to Statement class. With current implementation warnings produced in each prepared statement/cursor settle here.

Definition at line 613 of file session.h.

Allocation area for warnings and errors

Definition at line 301 of file session.h.


The documentation for this class was generated from the following files: